Collecting Tips with Ethereum

Tipping is a great way to show appreciation for someone's work and to help support them financially. But what if you could tip someone in a more automated, secure, and transparent way? Introducing the Web 3 Tip Jar a smart contract that allows people to send tips/donations to the contract owner. The contract is written in the Solidity programming language and is deployed to the Ethereum Mainnet & Goreli Testnet.

📚 Resources

📝 How it works

The contract is simple to use. All a user needs to do is send the desired amount of ETH to the contract address. When the owner wants to withdraw the funds they can call the withdrawTips function. This function will send the contract balance to the owner's address. It also contains an onlyOwner modifier to ensure only the owner can call this function. This is to prevent anyone from draining the contract. The transaction is completely secure and transparent as it is recorded on the blockchain.

Get Started

To get started you'll need to install Node.js and Yarn. Once you have those installed you need to run the command below to initialize a new Third Web project. Follow the instructions of the cli and make sure to choose the following options

Hardhat for framework,
Empty Contract for contract type,
None for extensions.

  npx thirdweb@latest create contract

cd into the project directory and open in your favorite code editor. Now when you open your contract in the contracts directory you'll see the following code.

contracts/Tipjar.sol

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

  contract TipJar {    

    constructor() { } 
  }

State Variables & Events

The first thing we need to do is add a state variable to keep track of the people who have sent tips to the contract. To acheive this we will use the mapping datatype provided by Solidity. Mappings allow the contract to store data in a key-value format, allowing the contract to easily access and modify the data. This is especially important for contracts that need to store large amounts of data, as it allows the data to be organized and easily accessed. Mappings also provide a secure way of storing data, as the data is stored on the blockchain and is immutable.

  /// @notice mapping to store tips and tipper
  /// @dev mapping is used to store data in a key-value format
  mapping(address => uint256) public tips;

We'll also need to add an events that will be emitted when someone tips the contract & when the owner withdraws the tips.

  /// @notice event to log tips collected
  /// @dev event is emitted when someone sends ether to the contract or calls sendTip function
  /// @param from the address of the tipper
  /// @param amount the tip amount
  event TipReceived(address indexed from, uint256 amount);
  
  /// @notice event to log tips withdrawn
  /// @param to the address of the owner
  /// @param amount the amount withdrawn
  event TipsWithdrawn(address indexed to, uint256 amount);

Now we need to make a modification to our constructor. We need to add a payable modifier to the constructor so that the contract can receive ETH.

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

  /// @title TipJar
  /// @author <YOUR_NAME>
  /// @notice This contract allows users to tip the owner
  /// @dev This contract is used to collect ethereum tips
  /// @dev Only the owner can withdraw the tips
  contract TipJar {    
    /// @notice mapping to store tips and tipper
    /// @dev mapping is used to store data in a key-value format
    mapping(address => uint256) public tips;

    /// @notice event to log tips collected
    /// @dev event is emitted when someone sends ether to the contract or calls sendTip function
    /// @param from the address of the tipper
    /// @param amount the tip amount
    event TipReceived(address indexed from, uint256 amount);
    
    /// @notice event to log tips withdrawn
    /// @param to the address of the owner
    /// @param amount the amount withdrawn
    event TipsWithdrawn(address indexed to, uint256 amount);

    constructor() payable { } 
  }

Functions & Modifiers

Now that we have our state variables and events we need to add some functions to interact with them. But before we do that lets create some modifiers first. Modifiers are used to modify the behavior of a function. Modifiers can be used to restrict access to functions, add additional logic, or even create new functions. They are a powerful tool for creating secure and efficient smart contracts. In our case we will use a modifier to verify that the amount being sent is greater than 0.

  /// @notice modifer to check if the tip amount is greater than 0
  /// @param _amount the tip amount to check
  modifier checkTipAmount(uint256 _amount) {
    require(_amount > 0, "TipJar: Tip amount must be greater than 0");
    _; // this line tells solidity to continue executing the function if the above condition is met
  }

Sweet! With that out of the way we can now add our functions. The first function we will add is the sendTip function. This function will allow users to send tips to the contract. Adding payable to a function in Solidity allows it to accept Ether payments. It also allows the function to be called with a value, which is the amount of Ether sent with the transaction.

  /// @notice funtion to send tips to this contract
  /// @dev can be called by anyone
  /// @dev is payable so it can receive ether
  /// @dev we use the checkTipAmount modifier to check if the tip amount is greater than 0
  /// @dev then we send the eth sent alongside this call to the contract balance
  function sendTip() 
  public 
  payable 
  checkTipAmount(msg.value) {
    (bool success, ) = payable(address(this)).call{value : msg.value}("");
    require(success == true, "TipJar: Transfer Failed"); 
  }

There's actually more than one way to send ethereum to a smart contract. Another way to send ether to a smart contract is to use the fallback function. The fallback function was introduced in Solidity v0.4.0, released in October 2016. It's a special function that is called when a user sends ether to the contract without calling any function. It's often used to provide a default behavior for a contract, such as providing a default response or logging the call. But for our use case we'll it as a redudant way to collect tips.

/// @notice fallback payable function to receive tips
/// @dev this function is called when a user sends ether to this contract
/// @dev we use the checkTipAmount modifier to validate the tip amount
receive() 
external 
payable 
checkTipAmount(msg.value) {
  // update mapping of tips
  tips[msg.sender] += msg.value;

  // emit event to log tips collected
  emit TipReceived(msg.sender, msg.value);
}

Now that we have a way to collect tips we need a way to see how many tips have been collected. To do this we will add a function that returns the current balance of the smart contract

  /// @notice function to get the total amount of tips collected
  /// @dev this function returns the total amount of tips collected
  /// @dev we use the view modifier to tell solidity that this function will not modify the state of the contract
  /// @dev we use the pure modifier to tell solidity that this function will not read from the state of the contract
  /// @return the total amount of tips collected
  function getContractBalance() 
  public 
  view 
  pure 
  returns(uint256) {
    return address(this).balance;
  }

Now that we have a way to send tips to the contract we need a way to withdraw the tips. We will add a function called withdrawTips that will allow the owner to withdraw the tips.

Permissions

Currently there is no mechanism to restrict access to the withdrawTips function. We want to make sure that only the owner can withdraw the funds. To do this we need to add the Ownable contract from OpenZeppelin. OpenZeppelin is a library of secure and battle-tested smart contracts that can be used to build decentralized applications. We will use the Ownable contract to restrict access to the withdrawTips function.

The Ownable contract also provides a modifier called onlyOwner that can be used to restrict access to a function. First, we need to import the Ownable contract from OpenZeppelin. And then we need to extend that contract.

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

import "@openzeppelin/contracts/access/Ownable.sol";

/// @title TipJar
/// @author <YOUR_NAME>
/// @notice This contract allows users to send tips to the owner
/// @dev This contract is used to collect crypto tips
/// @dev This contract allows the owner to withdraw the tips
contract TipJar is Ownable {
  // ...
}

Now we can add the withdrawTips function. We will use the onlyOwner modifier to restrict access to this function. And the owner() function to get the owner address for balance transfer. Technically speaking since were using the onlyOwner modifier we could subsitute the owner() function with msg.sender.

  /// @notice function to withdraw tips collected
  /// @dev uses the onlyOwner modifier from the Ownable contract
  function withdrawTips() 
  public 
  onlyOwner {
    // calculate the amount to withdraw
    uint256 amount = address(this).balance;

    require(address(this).balance > 0, "TipJar: Insufficient Balance");

    // transfer the amount to the owner
    payable(owner()).transfer(amount);

    // emit event to log tips withdrawn
    emit TipsWithdrawn(owner(), amount);
  }

👨🏾‍🔬 Testing

Now that we've finished the smart contract, its time to test it out. Testing out the the smart contract before deploying it is a good practice. It allows us to make sure that the smart contract is working as expected before we deploy it to the blockchain. Because the blockchain is immutable, once a smart contract is deployed it cannot be changed. Unless of course we deploy a new version of the contract or use a proxy contract. But that is a tutorial for another day.

First we need to create a directory called test in the root of our project. Then we need to create a file called TipJar.test.js in that directory.

mkdir test && touch test/TipJar.test.js

This contract is pretty straight forward, we will be testing the ability to

Send tips
- with insufficient balance
- with sufficient balance
Withdraw tips
- with insufficient balance
- with insufficient permissions
- with sufficient balance & permissions
Check the contract balance

Hardhat provides a local blockchain, which is a simulated blockchain that runs on our local machine. This allows us to test our smart contracts without having to deploy them to a real blockchain. We will use Hardhat to compile and deploy our smart contracts to the local blockchain. First create the boilerplate for the test file.

test/TipJar.test.js

import { loadFixture } from "@nomicfoundation/hardhat-network-helpers";
import { anyValue } from "@nomicfoundation/hardhat-chai-matchers/withArgs";
import { expect } from "chai";
import { ethers } from "hardhat";

describe("TipJar", function () {
  /**
   * Deploy the TipJar contract
   * 
   * reusable function to deploy the TipJar contract and return the contract instance
   */
  async function deployTipJar() {
    const [owner, otherAccount] = await ethers.getSigners();

    const TipJar = await ethers.getContractFactory("TipJar");
    const tips = await TipJar.deploy();
    const balance = await ethers.provider.getBalance(tips.address);

    return { tips, owner, otherAccount, balance };
  }
  // <TEST_GO_HERE>
});

Now we can start writing our tests.

✅ Deployment

We want to test that when the contract is deployed the owner variable is set to the address of the deployer. We also want to verify that the balance is initialized to 0.

  describe("Deployment", function () {
    it("Should set the right owner", async function () {
      const { tips, owner } = await loadFixture(deployTipJar);

      expect(await tips.owner()).to.equal(owner.address);
    });

    it("Balance should be empty", async function () {
      const { balance } = await loadFixture(deployTipJar);
      expect(balance).to.equal(ethers.utils.parseEther("0"));
    });
  });

✅ Send Tips

First we will test the ability to send tips to the contract. For both our fallback and sendTips function we want to ensure the apporitate error message gets displayed when sending a tip < 0. Lastly, for a valid tip we want to verify that the correct event gets emmited.

  describe("Transfers", function () {
    describe("Validations", function () {
      it("Fallback: Should revert with the right error if the amount is 0", async function () {
        const { tips, otherAccount } = await loadFixture(deployTipJar);

        await expect(
          tips.connect(otherAccount).signer.sendTransaction({
            to: tips.address,
            value: 0,
          })
        ).to.be.revertedWith("TipJar: Tip amount must be greater than 0");
      });

      it("Fallback: Balance should update on successful transfers", async function () {
        const { tips, otherAccount, balance } = await loadFixture(
          deployTipJar
        );
        await tips.connect(otherAccount).signer.sendTransaction({
          to: tips.address,
          value: 100,
        });
        expect(await ethers.provider.getBalance(tips.address)).to.equal(
          balance.add(100)
        );
      });

      it("Function: Should revert with the right error if the amount is 0", async function () {
        const { tips, otherAccount } = await loadFixture(deployTipJar);

        await expect(tips.connect(otherAccount).sendTip(0)).to.be.revertedWith(
          "TipJar: Tip amount must be greater than 0"
        );
      });

      it("Function: Balance should update on successful transfers", async function () {
        const { tips, otherAccount, balance } = await loadFixture(
          deployTipJar
        );
        await tips.connect(otherAccount).sendTip(100);
        expect(await ethers.provider.getBalance(tips.address)).to.equal(
          balance.add(100)
        );
      });
    });

    describe("Events", function () {
      it("Should emit an event on transfers", async function () {
        const { tips, otherAccount } = await loadFixture(deployTipJar);

        await expect(
          tips.connect(otherAccount).signer.sendTransaction({
            to: tips.address,
            value: 10,
          })
        )
          .to.emit(tips, "TipReceived")
          .withArgs(otherAccount.address, anyValue);
      });
    });
  });

✅ Withdraw Tips

Next we will test the ability to withdraw tips from the contract. We need to verify that only the owner has the ability to withdraw tips. The appropriate error message is returned if the owner tries to withdraw tips when the contract balance is 0. And lastly that the correct events get fired on withdrawal.

  describe("Withdrawals", function () {
    describe("Validations", function () {
      it("Should revert with the right error if called from not the owner", async function () {
        const { tips, otherAccount } = await loadFixture(deployTipJar);

        await expect(
          tips.connect(otherAccount).withdrawTips()
        ).to.be.revertedWith("Ownable: caller is not the owner");
      });

      it("Should revert with the right error if the balance is empty", async function () {
        const { tips, owner } = await loadFixture(deployTipJar);

        await expect(tips.connect(owner).withdrawTips()).to.be.revertedWith(
          "TipJar: Insufficient Balance"
        );
      });
    });

    describe("Events", function () {
      it("Should emit an event on withdrawals", async function () {
        const { tips, owner, balance, otherAccount } = await loadFixture(
          deployTipJar
        );
        await tips.connect(otherAccount).signer.sendTransaction({
          to: tips.address,
          value: 100,
        });
        await expect(tips.connect(owner).withdrawTips())
          .to.emit(tips, "TipsWithdrawn")
          .withArgs(owner.address, 100);
      });
    });
  });

🚀 Deploying the contract

Now that we have tested our smart contract we can deploy it to the Ethereum Mainnet. We will use Thirdweb to deploy our contract to the Ethereum Mainnet. The Thirdweb cli will automatically compile our contract and deploy it to the Ethereum Mainnet. So run the command below to deploy the contract, a new window will open in your browser and you will be prompted to sign the transaction. If you run into an issues make sure to follow this Deployment Guide

npx thirdweb@latest deploy

Conclusion

In conclusion, building a smart contract to send tips or donations is a powerful and effective way to support content creators and other creators online. By leveraging the security and transparency of the blockchain, smart contracts provide a trustless and decentralized platform for sending and receiving payments. In this blog, we walked through the steps of building a simple smart contract using the Solidity programming language, and we showed how easy it is to test, build & deploy smart contracts using the Thirdweb cli. I hope that this has provided some insight into the benefits of using smart contracts for payments, and that it will inspire you to explore the possibilities of this technology.