DEV Community: Obinna Duru

Integrating Trust: A Developer's Guide to the Resume Protocol

Obinna Duru — Sun, 21 Dec 2025 23:59:07 +0000

In my previous article, I introduced the Resume Protocol: a system designed to make professional reputation verifiable, soulbound, and owned by you.

But a protocol is only as useful as the tools we build to interact with it.

To bridge the gap between complex smart contracts and everyday utility, I built the Resume Integrator. This isn't just a script; it is a reference implementation designed to demonstrate reliability and excellence in Web3 engineering.

Whether you are building a freelance marketplace or a university certification portal, the challenge remains the same: linking rich off-chain evidence (PDFs, images) with on-chain truth (Immutable Ledgers).

In this guide, I will walk you through the thoughtful architectural decisions behind this integration.

The Engineering Challenge
Integrating a blockchain protocol requires us to reconcile two different realities:

The Evidence (Off-chain): The detailed descriptions, design portfolios, and certificates. These are heavy, and storing them on-chain is inefficient.
The Truth (On-chain): The cryptographic proof of ownership and endorsement.

My goal with the Resume Integrator was to stitch these together seamlessly, creating a system that is robust and user-centric.

The Architecture
I believe that good code tells a story. Here is the visual narrative of how an endorsement travels from a local environment to the blockchain.

Step 1: Structuring Data with Intent (The Metadata)
Clarity is the first step toward reliability. If we upload unstructured data, we create noise. To ensure our endorsements are interoperable with the wider Ethereum ecosystem: wallets, explorers, and marketplaces, we strictly adhere to the ERC-721 Metadata Standard.

I enforced this using strict TypeScript interfaces. We don't guess the shape of our data; we define it.

// From src/types.ts

export interface Attribute {
  trait_type: string;
  value: string | number | Date;
}

/**
 * Standard ERC-721 Metadata Schema
 * We use strict typing to ensure every credential we mint 
 * is readable by standard wallets.
 */
export interface CredentialMetadata {
  name: string;
  description: string;
  image: string;
  attributes: Attribute[];
}

Step 2: The Storage Layer (Pinata SDK)
For our "Evidence" layer, we need permanence. If I rely on a centralized server to host my resume data, my reputation is rented, not owned. That is a risk I am not willing to take.

We use IPFS (InterPlanetary File System) via the Pinata SDK. I chose Pinata because it offers the reliability of a managed service without compromising the decentralized nature of content addressing.

Here is the "Two-Step" pattern I implemented to ensure data integrity:

Upload the visual proof first.
Embed that proof's URI into the metadata.

// From src/storage.ts

/**
 * Creates NFT-compatible metadata for a credential
 * and uploads it to IPFS via Pinata.
 *
 * This function optionally uploads an image first,
 * then embeds its IPFS URL into the metadata JSON.
 * @param input Credential metadata fields
 *
 * @returns A public IPFS gateway URL pointing to the metadata JSON
 */
export async function createCredentialMetadata(
  input: CredentialMetadataInput
): Promise<string> {
  console.log("Authenticating with Pinata...");
  await pinata.testAuthentication();
  console.log("Pinata authentication successful");

  // Will store the IPFS URL of the uploaded image (if any)
  let image = "";

  // If an image path is provided, upload the image to IPFS first
  if (input.imagePath && fs.existsSync(input.imagePath)) {
    console.log(`Uploading image: ${input.imagePath}`);
    // Read the image file from disk into a buffer
    const buffer = fs.readFileSync(input.imagePath);

    // Convert the buffer into a File object (Node 18+ compatible)
    const file = new File([buffer], "credential.png", {
      type: "image/png",
    });

    // Upload the image to Pinata's public IPFS network
    const upload = await pinata.upload.public.file(file);

    // Construct a gateway-accessible URL using the returned CID
    image = `https://${CONFIG.PINATA_GATEWAY}/ipfs/${upload.cid}`;
    console.log(`   Image URL: ${image}`);
  } else if (input.imagePath) {
    console.warn(
      `Warning: Image path provided but file not found: ${input.imagePath}`
    );
  }

  // Construct ERC-721 compatible metadata JSON
  // This structure is widely supported by NFT platforms
  const metadata: CredentialMetadata = {
    name: input.skillName,
    description: input.description,
    image,
    attributes: [
      { trait_type: "Recipient", value: input.recipientName },
      { trait_type: "Endorser", value: input.issuerName },
      {
        trait_type: "Date",
        value: new Date(input.endorsementDate.toISOString().split("T")[0]!),
      },
      { trait_type: "Token Standard", value: "Soulbound (SBT)" },
    ],
  };

  // Upload the metadata JSON to IPFS
  console.log("Uploading metadata JSON...");
  const result = await pinata.upload.public.json(metadata);

  // Return a public gateway URL pointing to the metadata
  // This URL can be used directly as a tokenURI on-chain
  return `https://${CONFIG.PINATA_GATEWAY}/ipfs/${result.cid}`;
}

Step 3: The Issuance Layer (Viem)
With our data secured, we move to the "Truth" layer. We need to instruct the smart contract to mint a Soulbound Token that points to our metadata.

I chose Viem for this task. It is lightweight, type-safe, and aligns with my preference for precision over bloat.

The most critical engineering decision here is Waiting for Confirmation. In blockchain systems, broadcasting a transaction is not enough; we must ensure it is finalized. This prevents UI glitches and ensures the user knows exactly when their reputation is secured.

// From src/contract.ts

/**
 * Mint a new endorsement onchain
 */
export async function mintEndorsement(
  recipient: string,
  skill: string,
  dataURI: string
) {
  if (!CONFIG.CONTRACT_ADDRESS)
    throw new Error("Contract Address not set in .env");

  console.log(`Minting endorsement for ${skill}...`);

  const hash = await walletClient.writeContract({
    address: CONFIG.CONTRACT_ADDRESS,
    abi: CONTRACT_ABI,
    functionName: "endorsePeer",
    args: [recipient, skill, dataURI],
  });

  console.log(`   Tx Sent: ${hash}`);

  // Wait for confirmation
  const receipt = await publicClient.waitForTransactionReceipt({ hash });
  console.log(`Confirmed in block ${receipt.blockNumber}`);

  return hash;
}

Step 4: Verification (The Read)
A protocol is useless if we cannot retrieve the data efficiently.

Querying a blockchain state variable by variable is slow and expensive. Instead, we use Event Logs. By listening to the EndorsementMinted event, we can reconstruct a user's entire professional history in a single, efficient query. This is thoughtful engineering that respects both the network and the user's time.

// From src/contract.ts

/**
 * Find all endorsements for a specific user
 */
export async function getEndorsementsFor(userAddress: string) {
  if (!CONFIG.CONTRACT_ADDRESS)
    throw new Error("Contract Address not set in .env");

  console.log(`Querying endorsements for ${userAddress}...`);

  const logs = await publicClient.getLogs({
    address: CONFIG.CONTRACT_ADDRESS,
    event: parseAbiItem(
      "event EndorsementMinted(uint256 indexed tokenId, address indexed issuer, address indexed recipient, bytes32 skillId, string skill, uint8 status)"
    ),
    args: {
      recipient: userAddress as Hex,
    },
    fromBlock: "earliest",
  });

  return logs.map((log) => ({
    tokenId: log.args.tokenId,
    skill: log.args.skill,
    issuer: log.args.issuer,
    status: log.args.status === 1 ? "Active" : "Pending",
  }));
}

Conclusion
The Resume Integrator is more than a codebase. It is a blueprint for building with purpose.

By separating our concerns: using IPFS for heavy data and the Blockchain for trust, we create a system that is efficient, immutable, and scalable. By enforcing strict types and waiting for confirmations, we ensure reliability for our users.

The Resume Protocol is the foundation. This Integrator is the bridge. Now, it is up to you to build the interface.

Repositories:

The Protocol (Smart Contracts): github.com/obinnafranklinduru/nft-resume-protocol
The Integrator (Sample Client): github.com/obinnafranklinduru/resume-integrator

Let's build something you can trust with clarity, purpose, and excellence.

Your Career, Onchain: Building a Resume Protocol with Purpose and Trust

Obinna Duru — Sun, 21 Dec 2025 14:57:58 +0000

In the traditional world, a resume is just a PDF. It is a claim, not a proof. Anyone can write "Expert in Solidity" on a document, and verifying that claim requires trust, phone calls, and manual friction.

As a smart contract engineer, I look at systems through the lens of reliability. I asked myself: Why is our professional reputation: one of our most valuable assets, stored on fragile, centralized servers?

I wanted to solve this by building the Resume Protocol: a decentralized registry for peer-to-peer professional endorsements.

This isn't just about putting data on a blockchain. It is about engineering a system where trust is cryptographic, ownership is absolute, and the design is thoughtful. Here is how I built it.

The Problem: Trust is Fragile
We currently rely on platforms like LinkedIn to host our professional identities. While useful, these platforms have structural weaknesses:

Fabrication: Claims are self-reported and often unverified.
Centralization: Your endorsements live on a company's database. If they change their API or ban your account, your reputation vanishes.
Lack of Ownership: You rent your profile; you do not own it.

My mission was to engineer a solution where reliability is baked into the code. I wanted a system that was Verifiable (traceable to a real address), Soulbound (non-transferable), and Consensual (you control what appears on your profile).

The Solution: Soulbound Tokens (SBTs)
To engineer this, I utilized Soulbound Tokens (SBTs).

In technical terms, this is a modified ERC-721 token. Unlike a standard NFT, which is designed to be traded or sold, an SBT is bound to an identity. Think of it like a university degree or a Nobel Prize, it belongs to you, and you cannot sell it to someone else.

Traditional Resume vs. Onchain Protocol

Feature	Traditional Resume	Resume Protocol (Onchain)
Source	Self-claimed	Peer-verified
Ownership	Hosted by platforms	Owned by YOU (Soulbound)
Trust	Hard to verify	Cryptographically verifiable
Transferability	N/A	Non-transferable (Identity-bound)

By deploying this on Base, we leverage the security of Ethereum with the accessibility required for a global onchain economy.

The Architecture of Trust
Excellence in engineering means choosing clarity over complexity. The protocol works on a simple but rigorous state machine.

The Analogy: Imagine a Digital Award Ceremony.

The Issuer (your manager) decides to give you an award.
The Protocol (the stage) checks if they are allowed to give awards right now (Rate Limiting).
The Award (the Token) is presented to you.
The Status: It starts as "Pending" until you walk up and accept it.

The "Consent" Pattern
One of the most deliberate design choices I made was the Consent Mechanism.

In many onchain systems, if someone sends you a token, it just appears in your wallet. For a professional resume, this is a vulnerability. You do not want spam or malicious endorsements clogging your reputation.

Therefore, the protocol enforces a two-step lifecycle:

Pending: An issuer sends an endorsement. It sits in a "limbo" state.
Active: You, the recipient, must explicitly sign a transaction to acceptEndorsement.

This puts the user in control. It is a small detail, but it reflects a thoughtful approach to user safety.

This diagram shows how a user interacts with the system to send an endorsement.

A Look at the Code

Let's look at the heart of the endorsement logic. I wrote this in Solidity using Foundry for rigorous testing.

Notice the specific checks. Every line represents a decision to prioritize security and reliability.

    /**
     * @notice Peer-to-Peer Endorsement with Anti-Spam checks.
     * @dev Enforces Rate Limits. Mints as PENDING (requires acceptance).
     */
    function endorsePeer(address to, string calldata skill, string calldata dataURI) external {
        // 1. Rate Limit Check
        if (block.timestamp < lastEndorsementTimestamp[msg.sender] + RATE_LIMIT_COOLDOWN) {
            revert RateLimitExceeded();
        }

        // 2. Mint as Pending
        _mintEndorsement(msg.sender, to, skill, dataURI, Status.Pending);

        // 3. Update Timestamp (Checks-Effects-Interactions)
        lastEndorsementTimestamp[msg.sender] = uint64(block.timestamp);
    }

Making it "Soulbound"

To ensure the token behaves as a reputation marker and not a financial asset, we override the transfer logic.

function _update(address to, uint256 tokenId, address auth) internal override returns (address) {
        address from = _ownerOf(tokenId);
        if (from != address(0) && to != address(0)) {
            revert SoulboundNonTransferable();
        }
        return super._update(to, tokenId, auth);
    }

Engineering Excellence: Testing

Smart contracts handle real value and in this case, real reputations. Therefore, "it works on my machine" is not enough.
I used Foundry to subject this protocol to extensive verification:

Unit Tests: Verifying every state transition (Pending -> Active).
Fuzz Testing: I threw thousands of random inputs at the contract to ensure it handles edge cases gracefully.
Invariant Testing: Ensuring that no matter what happens, a user can never transfer their reputation token.

This rigor is what separates "code" from "engineering."

Building for the Future
I built the Resume Protocol because I believe the future of work is onchain. We are moving toward a world where your history, your skills, and your reputation are portable assets that you own.

This project is open-source. It is an invitation to collaborate. If you are a developer, a designer, or a builder who cares about clarity, purpose, and excellence, I invite you to review the code and contribute.

Repository: github.com/obinnafranklinduru/nft-resume-protocol

I am Obinna Duru, a Smart Contract Engineer dedicated to building reliable, secure, and efficient onchain systems.

Let's connect and build something you can trust..

📚 Beginner's Glossary

SBT (Soulbound Token): A non-transferable NFT. Once it's in your wallet, it's yours forever (unless revoked).
Smart Contract: A digital program stored on the blockchain that runs automatically when specific conditions are met.
Rate Limit: A security feature that prevents users from spamming the network by forcing them to wait between actions.
Foundry: A blazing fast toolkit for Ethereum application development written in Rust.
Onchain: Anything that lives directly on the blockchain.

"Smart contracts handle real value, so I build with reliability, thoughtfulness, and excellence."

Engineering Trust: My Journey Building a Decentralized Stablecoin

Obinna Duru — Mon, 01 Dec 2025 16:48:35 +0000

"Smart contracts handle real value."

This simple truth drives everything I do as an engineer. When we write code for the blockchain, we aren't just pushing pixels or serving data; we are building financial structures that people need to rely on. There is no customer support hotline in DeFi. If the math is wrong, the trust is broken.

That responsibility is why I decided to tackle my milestone project: a decentralized, crypto-backed stablecoin.

Inspired by the Cyfrin Updraft curriculum and the guidance of Patrick Collins (huge shoutout to the legend himself), I wanted to go beyond just copying a tutorial. I wanted to engineer a system that embodies my core values: Reliability, Thoughtfulness, and Excellence.

This article is my engineering journal. Whether you are a total beginner or a Solidity vet, I want to take you under the hood of how a digital dollar is actually built, the security patterns that keep it safe, and the lessons I learned along the way.

The "What": 3 Big Words, 1 Simple Concept
When I started, the technical definition of this project terrified me:

An Exogenous, Crypto-Collateralized, Algorithmic Stablecoin.

It sounds complicated, but let's strip away the jargon.

Exogenous: It is backed by assets outside the protocol (like Ethereum and Bitcoin), not by its own token. This prevents the "death spiral" we saw with Terra/Luna.
Crypto-Collateralized: You can't just print money. You have to deposit crypto assets (Collateral) first.
Algorithmic: There is no central bank. A smart contract does the math to decide if you are rich enough to mint more money.

The Architecture: The Cash, The Brain, and The Eyes

One of the first decisions I made was to separate concerns. Monolithic code is dangerous code. Instead, I built a modular system relying on three distinct pillars.

1. The Cash: DecentralizedStableCoin.sol
Think of this contract as the physical paper bills.

It is an ERC20 token (like USDC or DAI).
Key Detail: It is "owned" by the Engine. I wrote it so that no one, not even me, can mint tokens manually. Only the logic of the Engine can trigger the printer.

2. The Brain: DSCEngine.sol
This is where the magic (and the math) happens.
This contract:

Holds the user's collateral.
Tracks everyone's debt.
Calculates the "Health Factor" (more on this soon).
Enforces the rules of the system.

3. The Eyes: OracleLib.sol
Blockchains are isolated; they don't know that the price of Bitcoin changed 5 minutes ago. We need "Oracles" specifically Chainlink Data Feeds to bridge that gap. I wrapped these feeds in a custom library called OracleLib to add extra safety checks. If the Oracle goes silent (stale data), my system pauses to prevent catastrophe.

The Mechanics: How to Print Digital Money
Let's walk through a scenario. Imagine you want to borrow $100 of my stablecoin (let's call it BUSC).

The "Bank Vault" Rule (Over-Collateralization)
In traditional banking, they trust your credit score. In DeFi, we trust your assets. To borrow $100 of BUSC, the system forces you to deposit $200 worth of ETH.

Why the 200% requirement? Because crypto is volatile. If ETH crashes by 50% tomorrow, the protocol needs to ensure there is still enough value in the vault to back the stablecoin.

The Health Factor ❤️
This is the heartbeat of the protocol. I implemented a function called _healthFactor() that runs every time a user tries to do anything.

Health Factor = (Collateral Value X Liquidation Threshold) / Total Debt

Health Factor > 1: You are safe.
Health Factor = 1: You are on the edge.
Health Factor < 1: DANGER. You are insolvent.

If a user tries to mint enough BUSC to drop their health factor below 1, the transaction simply reverts (fails). The code refuses to let them make a bad financial decision.

The "Necessary Evil": Liquidation
This was the hardest concept for me to wrap my head around initially, but it is the most crucial for reliability.

What happens if the price of ETH crashes? If User A has $100 of debt and their collateral drops to $90, the system is broken. The stablecoin is no longer stable.

To prevent this, we have Liquidators.

Think of Liquidators as the protocol's cleanup crew.

They monitor the blockchain for insolvent users.
They pay off the bad debt (burning their own BUSC).
The Incentive: The protocol rewards them with the user's collateral plus a 10% bonus.

It sounds harsh, but it's fair. It ensures that bad debt is wiped out by the free market, keeping the protocol solvent for everyone else.

Security Patterns: Engineering for Excellence
Building this wasn't just about making it work; it was about making it secure. Here are two specific patterns I used to protect user funds.

1. The Pull-Over-Push Pattern
In early smart contracts, if the protocol owed you money, it would automatically "push" it to your wallet.

The Risk: If your wallet was a malicious contract, it could reject the transfer, causing the entire protocol to freeze (Denial of Service).
My Solution: I used the "Pull" pattern. The protocol updates your balance, but you have to initiate the withdrawal. This shifts the risk away from the protocol and puts control in the user's hands.

2. Staleness Checks on Oracles
What if Chainlink goes down? What if the price of ETH freezes at $2,000 while the real world crashes to $500? If I blindly trusted the Oracle, users could drain the vault.

I implemented a check in OracleLib:

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

import { AggregatorV3Interface } from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol";

/**
 * @title OracleLib
 * @author Obinna Franklin Duru
 * @notice This library is used to check the Chainlink Oracle for stale data.
 * If a price is stale, functions will revert, rendering the DSCEngine unusable - this is by design.
 * We want the DSCEngine to freeze if prices are not accurate.
 *
 * If the Chainlink network explodes and you have a lot of money locked in the protocol... too bad.
 */
library OracleLib {
    error OracleLib__StalePrice();

    uint256 private constant TIMEOUT = 3 hours; // 3 * 60 * 60 = 10800 seconds

    function staleCheckLatestRoundData(AggregatorV3Interface priceFeed)
        public
        view
        returns (uint80, int256, uint256, uint256, uint80)
    {
        (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound) =
            priceFeed.latestRoundData();

        if (updatedAt == 0 || answeredInRound < roundId) {
            revert OracleLib__StalePrice();
        }

        uint256 secondsSince = block.timestamp - updatedAt;
        if (secondsSince > TIMEOUT) {
            revert OracleLib__StalePrice();
        }

        return (roundId, answer, startedAt, updatedAt, answeredInRound);
    }
}

This is thoughtfulness in code. I'd rather have the protocol stop working temporarily than function incorrectly.

Testing: The "Aha!" Moment
I didn't just write unit tests. I learned Stateful Invariant Fuzzing.

Standard tests check: "Does 1 + 1 = 2?"
Fuzz tests scream: "What happens if I send random numbers, empty data, and massive values all at once?"

I wrote a test called invariant_protocolMustHaveMoreValueThanTotalSupply. It runs thousands of random scenarios: deposits, crashes, liquidations and constantly checks one golden rule:

The value in the vault MUST always be greater than the total supply of stablecoins.

Watching those tests pass was the moment I realized: This system is actually robust.

Final Thoughts
This project was more than just a repo on my GitHub. It was a masterclass in risk management, system design, and the ethos of Web3.

We are building the future of finance. That future demands reliability: systems that don't break when the market panics. It demands thoughtfulness: code that anticipates failure. And it demands excellence: refusing to settle for "good enough."

I am excited to take these lessons into my next project. If you want to see the code, break it, or build on top of it, check out the repo below.

Link to GitHub Repo

Let's build something you can trust.

📚 The DeFi Glossary (For the Curious)
If you are new to Web3, some of these terms might feel like alien language. Here is a cheat sheet I wish I had when I started:

Smart Contract: A digital agreement that lives on the blockchain. It executes automatically, no middlemen, no "I'll pay you Tuesday."
Stablecoin: A cryptocurrency designed to stay at a fixed value (usually $1.00), avoiding the wild price swings of Bitcoin or Ethereum.
Collateral: Assets (like ETH or BTC) that you lock up to secure a loan. Think of it like pawning a watch to get cash, but you get the watch back when you repay.
Peg: The target price of the stablecoin (e.g., "Pegged to $1.00").
Minting: The act of creating new tokens. In this protocol, you "mint" stablecoins when you lock up collateral.
Burning: The opposite of minting. It permanently destroys tokens, removing them from circulation (usually when you repay a debt).
Liquidator: A user (usually a bot) who monitors the system for risky loans. They pay off bad debt to keep the system safe and earn a profit for doing so.
Solvency: Being able to pay what you owe. If the protocol has $100 of assets and $90 of debt, it is solvent. If it has $100 of debt and $90 of assets, it is insolvent.
Oracle: A service (like Chainlink) that fetches real-world data (like the price of Gold or ETH) and puts it on the blockchain for smart contracts to read.

Monad is Fast. Your Code Should Be Reliable. (A New Foundry Starter Kit)

Obinna Duru — Fri, 28 Nov 2025 13:11:06 +0000

A thoughtful, hardened Foundry starter kit for building secure applications on Monad's 10,000 TPS network.

Speed Requires Stability

Monad is changing the conversation. With 10,000 TPS, 1-second finality, and parallel execution, it isn't just "another EVM chain", it is a high-performance engine for the next generation of onchain applications.

But in high-performance environments, reliability is everything.

When we build at speed, the cracks in our foundation show up faster. A default configuration might work for a hackathon, but does it communicate trust? Is it thoughtful enough to handle the nuances of via_ir optimization or the rigor of property-based fuzz testing?

I built the Monad Foundry Starter Kit to answer that question.

It is not just a template. It is a standard for Reliable, Thoughtful, and Excellent engineering on Monad.

Why Another Starter Kit?
The Monad team has done an incredible job with their official resources, providing a great entry point for developers. My goal isn't to replace that, but to harden it.

I wanted to build an environment that feels like a professional workshop where the tools are sharp, the safety protocols are in place, and the workflow is designed for craftsmanship, not just speed.

Here is how this kit brings Reliability and Thoughtfulness to your workflow.

1. Optimized for Monad's Engine (via_ir)
Monad's execution environment is highly optimized. To match that, your Solidity code should be too.

In this kit, the foundry.toml comes pre-configured with via_ir = true and the cancun EVM version. This ensures your contracts take full advantage of the Intermediate Representation (IR) optimization pipeline, which is crucial for gas efficiency and complex logic on a high-throughput chain.

[profile.default]
src = "src"
out = "out"
test = "test"
script = "script"
libs = ["lib"]

# Compiler Settings
solc_version = "0.8.24"
evm_version = "cancun"
optimizer = true
optimizer_runs = 200
via_ir = true

The Thoughtful Detail: Many devs forget to enable this until deployment day. We make it the default.

2. A Makefile That Speaks "Developer"
Complex Foundry commands are powerful, but they are also prone to typos. I've abstracted the complexity into a robust Makefile that handles the heavy lifting reliably.

Instead of remembering long flags for verification or deployment, you execute clear, intent-based commands:

make build          # Compiles with optimization
make test           # Runs Unit + Integration tests
make test-gas       # Generates a gas report
make deploy-testnet # Deploys reliably to Monad Testnet
make verify-testnet # Verifies on Blockvision/Sourcify

The Reliable Detail: The deploy commands include safety checks and clear separation between local (Anvil) and network (Monad) environments, preventing accidental mainnet deployments.

3. Testing: Beyond "It Works"
"It works on my machine" isn't enough for decentralized finance. This kit establishes a testing culture based on Negative Testing and Fuzzing.
- Unit Tests: We don't just test that a user can update a value; we explicitly test that unauthorized users revert.
- Fuzz Tests: Included by default (MonadGreeterFuzz.t.sol), running 10,000 randomized scenarios to catch edge cases you might miss.

The Excellent Detail: The kit includes a pre-built CI workflow (ci.yml) that enforces these tests on every Pull Request. You can't merge broken code.

Getting Started
Onboarding to Monad should be seamless. Here is how you can start building with clarity today.

Step 1: Clone the Standard

git clone https://github.com/obinnafranklinduru/monad-foundry-starter
cd /monad-foundry-starter
make install

Step 2: Secure Configuration
We use a thoughtful .gitignore strategy to keep your secrets safe.

cp .env.example .env
# Add your MONAD_TESTNET_RPC and PRIVATE_KEY

Step 3: Build & Deploy
Experience the flow.

make build
make test

When you are ready to go onchain:

make deploy-testnet

The Vision
We are part of a movement. Monad provides the speed; we provide the stability.

I believe that every line of code we write is a promise to the user. By starting with a foundation that values Reliability, Thoughtfulness, and Excellence, we aren't just deploying contracts-we are building an ecosystem that people can trust.

If you are a developer looking to build on Monad with precision, this kit is for you.

Repository: https://github.com/obinnafranklinduru/monad-foundry-starter
Connect: Twitter/X

Let's build something excellent.

Obinna Duru (BinnaDev) is a Smart Contract Engineer dedicated to building reliable, secure, and efficient onchain systems.

Building a Reusable, Multi-Event Soulbound NFT Contract in Solidity

Obinna Duru — Fri, 14 Nov 2025 10:46:22 +0000

As onchain engineers, our work handles real value. This demands reliability, thoughtfulness, and a security-first mindset. We aren't just building innovative systems; we're building systems people can trust.

I engineered a production-ready EventCertificate contract for issuing soulbound (non-transferable) attendance certificates. The primary goal wasn't just to mint an NFT; it was to build a scalable, secure, and reusable onchain framework that could serve hundreds of future events from a single deployed contract.

Deploying a new contract for every event is gas-intensive, a maintenance nightmare, and fragments a project's onchain identity. I want to share the architecture of my solution, focusing on the design patterns that make it robust and efficient.

You can find the full project here, including the backend relayer and frontend DApp:

The High-Level System Architecture
Before diving into the contract, here's the end-to-end flow. It starts with the off-chain organizer preparing the metadata and Merkle tree, and ends with the on-chain contract verifying the relayer's mint transaction.

If the image appears blurred, you can view it clearly here.

1. The "Campaign" Model: A Multi-Tenant Architecture
Instead of a one-and-done contract, I implemented a "Campaign" model. This allows a single EventCertificate instance to manage an unlimited number of distinct minting events.

The core of this is the MintingCampaign struct:

struct MintingCampaign {
    bytes32 merkleRoot;  // Unique whitelist for this event
    uint256 startTime;   // When minting can begin
    uint256 endTime;     // When minting ends
    uint256 maxMints;    // Supply cap for this campaign
    bool isActive;       // Admin-controlled toggle
}

A mapping, mapping(uint256 => MintingCampaign) public campaigns;, stores each campaign by a unique campaignId.

Why is this better?

Scalability: The owner can launch new events simply by calling createCampaign(), a simple storage-writing transaction. No re-deployment needed.
Efficiency: All events share the same core logic, which is far more gas-efficient.
Clarity: It provides a single, trusted onchain source for all of an organization's events, rather than a dozen different contract addresses.

2. The Trusted Relayer & Merkle Whitelisting
Security and user experience were non-negotiable. This system needed to be both secure against bots and provide a gasless minting experience for attendees. The solution was a combination of Merkle Proofs and a trusted relayer.

Merkle Proofs for Scalable Whitelists
We can't store 10,000 addresses in an onchain array. The merkleRoot in the MintingCampaign struct is the key. Off-chain, we generate a Merkle tree from the list of attendee addresses. To mint, a user must provide a valid merkleProof for their address.

The contract verifies this with a single, efficient check using OpenZeppelin's library:

bytes32 leaf = keccak256(abi.encodePacked(attendee));
if (!MerkleProof.verify(merkleProof, campaign.merkleRoot, leaf)) {
    revert InvalidProof();
}

The Trusted Relayer Pattern
The mint function has a critical modifier:

function mint(
    address attendee,
    uint256 campaignId,
    bytes32[] calldata merkleProof
) external whenNotPaused {
    if (msg.sender != relayer) revert NotAuthorizedRelayer();
    // ... all other logic
}

Only a trusted relayer address (set in the constructor and updatable by the owner) can call mint().

This design is powerful:

Gasless Experience: Attendees simply sign a message (or interact with a frontend). The relayer (a backend service) takes their proof, constructs the transaction, and pays the gas. For the user, the mint is free.
Security Gate: It serves as a backend-level defense. We can add API rate-limiting or other checks before the relayer even tries to submit the transaction, protecting the contract from DDoS or spam.
Proof Validation: The relayer's backend can pre-verify the Merkle proof before spending gas on a transaction that might fail, saving money and network congestion.

3. Enforcing "Soulbound" with Clarity
A certificate of achievement is meaningless if it can be sold. These NFTs must be non-transferable.

While ERC-4973 is a common standard, for this use case, a simple and clear override of the OpenZeppelin ERC721 _update function is the most direct and reliable approach. _update is the internal function called by _transfer, _mint, and _burn.

We only want to allow minting (where from is address(0)) and burning (where to is address(0)). Any other combination is a transfer.

/// @notice Soulbound and Metadata Logic
function _update(
    address to,
    uint256 tokenId,
    address auth
) internal override returns (address) {
    address from = _ownerOf(tokenId);

    // Revert if 'from' AND 'to' are not address(0).
    // This allows mints (from == 0) and burns (to == 0),
    // but blocks all transfers (from != 0 && to != 0).
    if (from != address(0) && to != address(0)) {
        revert NonTransferable();
    }

    return super._update(to, tokenId, auth);
}

This code is simple, clear, and effectively makes the tokens soulbound.

4. Deterministic Metadata Linked to the Owner
This is a subtle but important piece of thoughtful design. Most NFTs link metadata to the tokenId. But for this system, the certificate is personalized to the attendee.

What if we needed to burn and re-issue a certificate? The tokenId would change, but the attendee's address would not.

Therefore, the tokenURI function is designed to be deterministic based on the owner's address, not the tokenId.

function tokenURI(uint256 tokenId)
    public view override returns (string memory)
{
    address ownerAddr = _ownerOf(tokenId);
    if (ownerAddr == address(0)) revert NonExistentToken();

    // 1. Find which campaign this token belongs to
    uint256 campaignId = tokenToCampaignId[tokenId];

    // 2. Get the specific baseURI for THAT campaign
    string memory baseURI = campaignBaseURI[campaignId];
    if (bytes(baseURI).length == 0) revert NonExistentToken();

    // 3. Convert owner's address to a string
    string memory addrStr = _toAsciiString(ownerAddr);

    // 4. Concatenate: baseURI + 0xaddress.json
    return string.concat(baseURI, addrStr, ".json");
}

The off-chain script (shown in the system flow) generates personalized JSON metadata named by the user's address (e.g., 0x....json). The contract's tokenURI function simply rebuilds this path. This is a robust, reliable way to link personalized metadata.

The Full Smart Contract Code
For complete reference, here is the full implementation of EventCertificate.sol.

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

import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import {Ownable, Ownable2Step} from "@openzeppelin/contracts/access/Ownable2Step.sol";
import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";
import {MerkleProof} from "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";

/// @title EventCertificate
/// @author Obinna Franklin Duru
/// @notice A reusable, pausable, and soulbound ERC721 certificate contract for multiple events.
/// @dev Manages minting "campaigns" with unique whitelists, timelines, and mint limits.
/// A trusted relayer facilitates gasless minting for whitelisted participants.
contract EventCertificate is ERC721, Ownable2Step, Pausable {
    // --- Custom Errors ---
    error NotAuthorizedRelayer();
    error AlreadyMinted();
    error InvalidProof();
    error NonTransferable();
    error NonExistentToken();
    error ZeroAddress();
    error CampaignNotActive();
    error CampaignDoesNotExist();
    error InvalidCampaignTimes();
    error CampaignMustStartInFuture();
    error EmptyMerkleRoot();
    error MintingWindowNotOpen();
    error ProofTooLong();
    error InvalidInput();
    error CannotModifyStartedCampaign();
    error MintLimitReached();
    error CampaignDurationTooLong();
    error CampaignExpired();
    error CampaignHasMints();

    // --- Constants ---
    uint256 private constant MAX_PROOF_DEPTH = 500;
    uint256 private constant MAX_CAMPAIGN_DURATION = 365 days;

    // --- Structs ---
    /// @notice Holds all parameters for a single minting event.
    struct MintingCampaign {
        bytes32 merkleRoot;
        uint256 startTime;
        uint256 endTime;
        uint256 maxMints;
        bool isActive;
    }

    // --- State Variables ---
    address public relayer;
    mapping(uint256 => MintingCampaign) public campaigns;
    mapping(uint256 => mapping(address => bool)) public hasMintedInCampaign;
    mapping(uint256 => uint256) public campaignMintCount;
    mapping(uint256 => uint256) public tokenToCampaignId;
    mapping(uint256 => string) public campaignBaseURI;
    uint256 private _nextTokenId = 1;
    uint256 private _nextCampaignId = 1;

    // --- Events ---
    event CertificateMinted(address indexed attendee, uint256 indexed tokenId, uint256 indexed campaignId);
    event CampaignCreated(
        uint256 indexed campaignId, bytes32 merkleRoot, uint256 startTime, uint256 endTime, uint256 maxMints
    );
    event CampaignUpdated(uint256 indexed campaignId, bytes32 newMerkleRoot, uint256 newStartTime, uint256 newEndTime);
    event CampaignActiveStatusChanged(uint256 indexed campaignId, bool isActive);
    event CampaignDeleted(uint256 indexed campaignId);
    event RelayerUpdated(address newRelayer);
    event CampaignBaseURIUpdated(uint256 indexed campaignId, string newBaseURI);

    // --- Constructor ---
    /// @notice Initializes the contract with core, immutable parameters.
    /// @param name_ The name of the ERC721 token collection.
    /// @param symbol_ The symbol of the ERC721 token collection.
    /// @param relayer_ The trusted address that will pay gas fees for minting.
    constructor(string memory name_, string memory symbol_, address relayer_)
        ERC721(name_, symbol_)
        Ownable(msg.sender)
    {
        if (bytes(name_).length == 0 || bytes(symbol_).length == 0) {
            revert InvalidInput();
        }
        if (relayer_ == address(0)) revert ZeroAddress();

        relayer = relayer_;
    }

    // --- Minting Function (Relayer Only) ---
    /// @notice Mints a soulbound certificate to an attendee for a specific campaign.
    /// @dev Checks campaign status, time windows, mint limits, and Merkle proof validity.
    /// @param attendee The address that will receive the certificate NFT.
    /// @param campaignId The ID of the campaign the user is minting for.
    /// @param merkleProof An array of bytes32 hashes forming the Merkle proof.
    function mint(address attendee, uint256 campaignId, bytes32[] calldata merkleProof) external whenNotPaused {
        if (attendee == address(0)) revert ZeroAddress();
        if (msg.sender != relayer) revert NotAuthorizedRelayer();
        if (merkleProof.length > MAX_PROOF_DEPTH) revert ProofTooLong();

        MintingCampaign storage campaign = campaigns[campaignId];

        if (campaign.merkleRoot == bytes32(0)) revert CampaignDoesNotExist();
        if (!campaign.isActive) revert CampaignNotActive();
        if (block.timestamp < campaign.startTime || block.timestamp > campaign.endTime) {
            revert MintingWindowNotOpen();
        }
        if (hasMintedInCampaign[campaignId][attendee]) revert AlreadyMinted();
        if (campaignMintCount[campaignId] >= campaign.maxMints) revert MintLimitReached();

        bytes32 leaf = keccak256(abi.encodePacked(attendee));
        if (!MerkleProof.verify(merkleProof, campaign.merkleRoot, leaf)) {
            revert InvalidProof();
        }

        uint256 tokenId = _nextTokenId;
        hasMintedInCampaign[campaignId][attendee] = true;
        campaignMintCount[campaignId]++;
        tokenToCampaignId[tokenId] = campaignId;

        unchecked {
            _nextTokenId++;
        }

        emit CertificateMinted(attendee, tokenId, campaignId);
        _safeMint(attendee, tokenId);
    }

    // --- Admin Functions ---

    /// @notice Creates a new minting campaign. Campaigns are inactive by default.
    /// @param merkleRoot The whitelist Merkle root.
    /// @param startTime The Unix timestamp for when minting begins.
    /// @param endTime The Unix timestamp for when minting ends.
    /// @param maxMints The maximum number of NFTs that can be minted for this campaign.
    function createCampaign(
        bytes32 merkleRoot,
        uint256 startTime,
        uint256 endTime,
        uint256 maxMints,
        string calldata baseURI_
    ) external onlyOwner {
        if (bytes(baseURI_).length == 0) revert InvalidInput();
        if (startTime < block.timestamp) revert CampaignMustStartInFuture();
        if (startTime >= endTime) revert InvalidCampaignTimes();
        if (endTime - startTime > MAX_CAMPAIGN_DURATION) revert CampaignDurationTooLong();
        if (merkleRoot == bytes32(0)) revert EmptyMerkleRoot();

        uint256 campaignId = _nextCampaignId;
        campaigns[campaignId] = MintingCampaign({
            merkleRoot: merkleRoot,
            startTime: startTime,
            endTime: endTime,
            maxMints: maxMints,
            isActive: false
        });

        campaignBaseURI[campaignId] = baseURI_;

        unchecked {
            _nextCampaignId++;
        }
        emit CampaignCreated(campaignId, merkleRoot, startTime, endTime, maxMints);
    }

    /// @notice Updates the parameters of a campaign BEFORE it has started.
    /// @param campaignId The ID of the campaign to update.
    /// @param newMerkleRoot The new whitelist Merkle root.
    /// @param newStartTime The new start time.
    /// @param newEndTime The new end time.
    function updateCampaignBeforeStart(
        uint256 campaignId,
        bytes32 newMerkleRoot,
        uint256 newStartTime,
        uint256 newEndTime
    ) external onlyOwner {
        MintingCampaign storage campaign = campaigns[campaignId];
        if (campaign.merkleRoot == bytes32(0)) revert CampaignDoesNotExist();
        if (block.timestamp >= campaign.startTime) revert CannotModifyStartedCampaign();

        if (newStartTime < block.timestamp) revert CampaignMustStartInFuture();
        if (newStartTime >= newEndTime) revert InvalidCampaignTimes();
        if (newEndTime - newStartTime > MAX_CAMPAIGN_DURATION) revert CampaignDurationTooLong();
        if (newMerkleRoot == bytes32(0)) revert EmptyMerkleRoot();

        campaign.merkleRoot = newMerkleRoot;
        campaign.startTime = newStartTime;
        campaign.endTime = newEndTime;

        emit CampaignUpdated(campaignId, newMerkleRoot, newStartTime, newEndTime);
    }

    /// @notice Deletes a campaign that was created by mistake.
    /// @dev Can only be called before the campaign starts, if it's inactive, and if no mints have occurred.
    /// @param campaignId The ID of the campaign to delete.
    function deleteCampaign(uint256 campaignId) external onlyOwner {
        MintingCampaign storage campaign = campaigns[campaignId];
        if (campaign.merkleRoot == bytes32(0)) revert CampaignDoesNotExist();
        if (campaign.isActive) revert CampaignNotActive(); // Must be inactive
        if (block.timestamp >= campaign.startTime) revert CannotModifyStartedCampaign();
        if (campaignMintCount[campaignId] > 0) revert CampaignHasMints(); // Cannot delete if mints exist

        delete campaigns[campaignId];
        emit CampaignDeleted(campaignId);
    }

    /// @notice Activates or deactivates a campaign.
    /// @param campaignId The ID of the campaign to modify.
    /// @param isActive The new active status.
    function setCampaignActiveStatus(uint256 campaignId, bool isActive) external onlyOwner {
        MintingCampaign storage campaign = campaigns[campaignId];
        if (campaign.merkleRoot == bytes32(0)) revert CampaignDoesNotExist();

        if (isActive) {
            // if (block.timestamp < campaign.startTime) revert MintingWindowNotOpen();
            if (block.timestamp > campaign.endTime) revert CampaignExpired();
        }

        campaign.isActive = isActive;
        emit CampaignActiveStatusChanged(campaignId, isActive);
    }

    /// @notice Allows the contract owner to burn (revoke) a certificate NFT.
    /// @param tokenId The token ID to burn.
    function burn(uint256 tokenId) external onlyOwner {
        address ownerAddr = _ownerOf(tokenId);
        if (ownerAddr == address(0)) revert NonExistentToken();

        uint256 campaignId = tokenToCampaignId[tokenId];
        if (campaignId == 0) revert NonExistentToken();

        // Mark user as eligible to re-mint if needed
        if (hasMintedInCampaign[campaignId][ownerAddr]) {
            hasMintedInCampaign[campaignId][ownerAddr] = false;
        }

        // Reduce mint count on campaign if needed
        if (campaignMintCount[campaignId] > 0) {
            campaignMintCount[campaignId]--;
        }

        delete tokenToCampaignId[tokenId];

        _burn(tokenId);
    }

    /// @notice Pauses all minting in an emergency.
    function pause() external onlyOwner {
        _pause();
    }

    /// @notice Resumes minting after a pause.
    function unpause() external onlyOwner {
        _unpause();
    }

    /// @notice Updates the trusted relayer address.
    /// @param newRelayer The address of the new relayer.
    function updateRelayer(address newRelayer) external onlyOwner {
        if (newRelayer == address(0)) revert ZeroAddress();
        relayer = newRelayer;
        emit RelayerUpdated(newRelayer);
    }

    /// @notice Updates the base URI for a campaign (metadata storage location).
    /// @dev Can be called at any time by owner, even after minting, to fix metadata issues.
    /// @param campaignId The campaign whose metadata URI should be updated.
    /// @param newBaseURI The new base URI pointing to updated metadata.
    function updateCampaignBaseURI(uint256 campaignId, string calldata newBaseURI) external onlyOwner {
        MintingCampaign storage campaign = campaigns[campaignId];
        if (campaign.merkleRoot == bytes32(0)) revert CampaignDoesNotExist();
        if (bytes(newBaseURI).length == 0) revert InvalidInput();

        campaignBaseURI[campaignId] = newBaseURI;
        emit CampaignBaseURIUpdated(campaignId, newBaseURI);
    }

    // --- View Functions ---

    /// @notice Gets all data for a specific campaign.
    /// @param campaignId The ID of the campaign.
    /// @return A MintingCampaign struct in memory.
    function getCampaign(uint256 campaignId) external view returns (MintingCampaign memory) {
        return campaigns[campaignId];
    }

    /// @notice Checks if a user meets the basic requirements to mint (does not check Merkle proof).
    /// @param attendee The address to check.
    /// @param campaignId The campaign to check against.
    /// @return A boolean indicating if the user meets the current criteria to mint.
    function canMint(address attendee, uint256 campaignId) external view returns (bool) {
        MintingCampaign storage campaign = campaigns[campaignId];
        if (!campaign.isActive || campaign.merkleRoot == bytes32(0)) return false;
        if (block.timestamp < campaign.startTime || block.timestamp > campaign.endTime) return false;
        if (hasMintedInCampaign[campaignId][attendee]) return false;
        if (campaignMintCount[campaignId] >= campaign.maxMints) return false;
        return true;
    }

    // --- Soulbound and Metadata Logic ---

    function _update(address to, uint256 tokenId, address auth) internal override returns (address) {
        address from = _ownerOf(tokenId);
        if (from != address(0) && to != address(0)) {
            revert NonTransferable();
        }
        return super._update(to, tokenId, auth);
    }

    /// @notice Returns the metadata URI for a given token.
    /// @param tokenId The ID of the token.
    /// @return The metadata URI string.
    function tokenURI(uint256 tokenId) public view override returns (string memory) {
        address ownerAddr = _ownerOf(tokenId);
        if (ownerAddr == address(0)) revert NonExistentToken();

        // 1. Find which campaign this token belongs to
        uint256 campaignId = tokenToCampaignId[tokenId];

        // 2. Get the specific baseURI for THAT campaign
        string memory baseURI = campaignBaseURI[campaignId];
        if (bytes(baseURI).length == 0) revert NonExistentToken();

        string memory addrStr = _toAsciiString(ownerAddr);
        return string.concat(baseURI, addrStr, ".json");
    }

    /// @dev Helper function to convert an address to its lowercase hex string representation.
    function _toAsciiString(address x) internal pure returns (string memory) {
        // Convert the address to a bytes32 value by first converting to uint160 and then to uint256.
        // This ensures the address is padded to 32 bytes with leading zeros.
        bytes32 value = bytes32(uint256(uint160(x)));

        // Define the hexadecimal characters for lookup.
        bytes memory alphabet = "0123456789abcdef";

        // Create a bytes array of length 42: 2 bytes for '0x' and 40 bytes for the 20-byte address (each byte becomes two hex characters).
        bytes memory str = new bytes(42);
        str[0] = "0";
        str[1] = "x";

        // Loop through each byte of the address (20 bytes).
        for (uint256 i = 0; i < 20; i++) {
            // Extract the byte at position i + 12 from the bytes32 value.
            // The address is stored in the last 20 bytes of the 32-byte value, so we start at index 12.
            // Get the high nibble (4 bits) of the byte by shifting right by 4 bits.
            // Convert to uint8 to use as an index in the alphabet.
            str[2 + i * 2] = alphabet[uint8(value[i + 12] >> 4)];

            // Get the low nibble (4 bits) of the byte by masking with 0x0F.
            // Convert to uint8 to use as an index in the alphabet.
            str[3 + i * 2] = alphabet[uint8(value[i + 12] & 0x0f)];
        }
        // Convert the bytes array to a string and return it.
        return string(str);
    }

    /// @notice Returns the next token ID that will be minted.
    /// @return The next token ID.
    function nextTokenId() external view returns (uint256) {
        return _nextTokenId;
    }
}

Building for Trust
This contract is a reflection of my core philosophy: every line of code should communicate trust. By prioritizing a scalable multi-tenant architecture, layered security, and thoughtful design patterns like deterministic metadata, we create systems that are not just functional, but reliable and enduring.

I hope this breakdown was useful. I'm always open to discussing onchain architecture and security.

Let's build with clarity, purpose, and excellence.

Thanks for reading! If you found this article thoughtful and reliable, I'd appreciate a like or a comment.

To see more of my work on secure and efficient on-chain systems, feel free to visit my portfolio.

Building for Trust: A Guide to Gasless Transactions with ERC-2771

Obinna Duru — Thu, 13 Nov 2025 02:55:14 +0000

How to use ERC-2771 and a Merkle Airdrop contract to build thoughtful, user-first dApps by separating the gas-payer from the transaction authorizer.

As smart contract engineers, we build systems that handle real value. This demands a philosophy built on reliability, thoughtfulness, and excellence. Every line of code we write should communicate trust.

But what happens when the very design of the network creates friction that breaks this trust?

The Human Problem: Gas Fees
Imagine a common scenario: Alice is excited to claim her airdrop, a reward for being an early community member. She goes to the claim page, connects her wallet, but when she clicks "Claim", the transaction fails. The reason? She has no ETH in her wallet to pay for gas.

This is a critical failure in user experience. We’ve presented a user with a "gift" they cannot open.

As engineers, our first instinct might be to build a "relayer service." We could have a server, let's call it "Bob" that pays the gas on Alice's behalf.

The Technical Problem: msg.sender
This "thoughtful" solution immediately hits a technical wall: authorization.

In a standard transaction, the msg.sender (the address that initiated the call and is paying the gas) is the ultimate source of truth for authorization.

If Bob (the relayer) calls the claim() function and pays the gas, the contract sees: msg.sender = Bob.address

The contract now believes Bob is the one claiming the airdrop, not Alice. This breaks the entire authorization model.

How do we build a reliable system that separates "who is paying for gas" from "who is authorizing the action"?

The Principled Solution: ERC-2771
The community solved this through a standard: ERC-2771.

ERC-2771 is a standard for "meta-transactions" that provides a trusted, on-chain path to solve this very problem. It introduces a special "middleman" contract called a Trusted Forwarder.

Instead of a custom, off-chain solution, we use a clear, on-chain protocol. The new flow looks like this:

Alice (No ETH): Creates a signed message containing her desired transaction (e.g., "I, Alice, want to call claim()").
Relayer (Bob): Receives this signed message from Alice.
Relayer (Bob): Wraps Alice's message in a new transaction and sends it to the Trusted Forwarder, paying the gas.
Trusted Forwarder: Verifies Alice's signature is valid.
Trusted Forwarder: Calls our Airdrop contract, appending Alice's original address (Alice.address) to the end of the calldata.
Airdrop Contract: Receives the call from the Trusted Forwarder. Because it's a trusted contract, it knows to look at the end of the calldata to find the true authorizer (Alice).

This is the core of reliable, gasless design. Our contract's logic is no longer concerned with msg.sender (the gas payer) but with the true authorizer of the request.

A Practical Example: A Secure Merkle Airdrop
To demonstrate this, I built a MerkleAirdrop contract. The design goals were reliability, gas efficiency, and security with native support for gasless claims.

Here is the full contract:

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

import {MerkleProof} from "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";
import {BitMaps} from "@openzeppelin/contracts/utils/structs/BitMaps.sol";
import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
import {Context} from "@openzeppelin/contracts/utils/Context.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
import {IAirdrop} from "./interfaces/IAirdrop.sol";

/**
 * @title MerkleAirdrop
 * @author BinnaDev
 * @notice A modular, gas-efficient, and secure contract for airdrops
 * verified by Merkle proofs.
 * @dev This contract implements the `IAirdrop` interface, uses OpenZeppelin's
 * `BitMaps` for gas-efficient claim tracking, `ReentrancyGuard` for security,
 * and `ERC2771Context` to natively support gasless claims via a trusted
 * forwarder. The Merkle root is immutable, set at deployment for
 * maximum trust.
 */
contract MerkleAirdrop is IAirdrop, ERC2771Context, ReentrancyGuard {
    using BitMaps for BitMaps.BitMap;

    /**
     * @notice The MerMonitor's root of the Merkle tree containing all allocations.
     * @dev This is immutable, meaning it can only be set once at deployment.
     * This is a critical security feature to build trust with users,
     * as the rules of the airdrop can never change.
     */
    bytes32 public immutable MERKLE_ROOT;

    /**
     * @notice The maximum allowed depth for a Merkle proof.
     * @dev This is a security measure to prevent gas-griefing (DOS) attacks
     * where an attacker might submit an excessively long (but valid) proof.
     * 32 is a safe and generous default.
     */
    uint256 public constant MAX_PROOF_DEPTH = 32;

    /**
     * @notice The bitmap storage that tracks all claimed indices.
     * @dev We use the `BitMaps` library (composition) rather than inheriting
     * (inheritance) for better modularity and clarity.
     */
    BitMaps.BitMap internal claimedBitmap;

    /**
     * @notice Initializes the contract with the airdrop's Merkle root
     * and the trusted forwarder for gasless transactions.
     * @param merkleRoot The `bytes32` root of the Merkle tree.
     * @param trustedForwarder The address of the ERC-2771 trusted forwarder.
     * Pass `address(0)` if gasless support is not needed.
     */
    constructor(bytes32 merkleRoot, address trustedForwarder) ERC2771Context(trustedForwarder) {
        MERKLE_ROOT = merkleRoot;
    }

    /**
     * @notice Claims an airdrop allocation by providing a valid Merkle proof.
     * @dev This function follows the Checks-Effects-Interactions pattern.
     * It uses `_msgSender()` to support both direct calls and gasless claims.
     * @param index The unique claim index for this user (from the Merkle tree data).
     * @param claimant The address that is eligible for the claim.
     * @param tokenContract The address of the ERC20 or ERC721 token.
     * @param tokenId The ID of the token (for ERC721); must be 0 for ERC20.
     * @param amount The amount of tokens (for ERC20); typically 1 for ERC721.
     * @param proof The Merkle proof (`bytes32[]`) showing the leaf is in the tree.
     */
    function claim(
        uint256 index,
        address claimant,
        address tokenContract,
        uint256 tokenId,
        uint256 amount,
        bytes32[] calldata proof
    ) external nonReentrant {
        // --- CHECKS ---

        // 1. Check if this index is already claimed (Bitmap check).
        // This is the cheapest check and should come first.
        if (claimedBitmap.get(index)) {
            revert MerkleAirdrop_AlreadyClaimed(index);
        }

        // 2. Check for proof length (Gas-griefing DOS protection).
        if (proof.length > MAX_PROOF_DEPTH) {
            revert MerkleAirdrop_ProofTooLong(proof.length, MAX_PROOF_DEPTH);
        }

        // 3. Check that the sender is the rightful claimant.
        // We use `_msgSender()` to transparently support ERC-2771.
        address sender = _msgSender();
        if (claimant != sender) {
            revert MerkleAirdrop_NotClaimant(claimant, sender);
        }

        // 4. Reconstruct the leaf on-chain.
        // This is a critical security step. We NEVER trust the client
        // to provide the leaf hash directly.
        bytes32 leaf = _hashLeaf(index, claimant, tokenContract, tokenId, amount);

        // 5. Verify the proof (Most expensive check).
        if (!MerkleProof.verify(proof, MERKLE_ROOT, leaf)) {
            revert MerkleAirdrop_InvalidProof();
        }

        // --- EFFECTS ---

        // 6. Mark the index as claimed *before* the interaction.
        // This satisfies the Checks-Effects-Interactions pattern and
        // mitigates reentrancy risk.
        claimedBitmap.set(index);

        // --- INTERACTIONS ---

        // 7. Dispatch the token.
        _dispatchToken(tokenContract, claimant, tokenId, amount);

        // 8. Emit the standardized event.
        emit Claimed("Merkle", index, claimant, tokenContract, tokenId, amount);
    }

    /**
     * @notice Public view function to check if an index has been claimed.
     * @param index The index to check.
     * @return bool True if the index is claimed, false otherwise.
     */
    function isClaimed(uint256 index) public view returns (bool) {
        return claimedBitmap.get(index);
    }

    /**
     * @notice Internal function to hash the leaf data.
     * @dev Must match the exact hashing scheme used in the off-chain
     * generator script. We use a double-hash (H(H(data))) pattern
     * with `abi.encode` for maximum security and standardization.
     * `abi.encode` is safer than `abi.encodePacked` as it pads elements.
     */
    function _hashLeaf(uint256 index, address claimant, address tokenContract, uint256 tokenId, uint256 amount)
        internal
        pure
        returns (bytes32)
    {
        // First hash: abi.encode() is safer than abi.encodePacked()
        // as it pads all elements, preventing ambiguity.
        bytes32 innerHash = keccak256(abi.encode(index, claimant, tokenContract, tokenId, amount));

        // Second hash: This is a standard pattern to ensure all leaves
        // are a uniform hash-of-a-hash.
        return keccak256(abi.encode(innerHash));
    }

    /**
     * @notice Internal function to dispatch the tokens (ERC20 or ERC721).
     * @dev Assumes this contract holds the full supply of airdrop tokens.
     */
    function _dispatchToken(address tokenContract, address to, uint256 tokenId, uint256 amount) internal {
        if (tokenId == 0) {
            // This is an ERC20 transfer.
            if (amount == 0) revert Airdrop_InvalidAllocation();
            bool success = IERC20(tokenContract).transfer(to, amount);
            if (!success) revert Airdrop_TransferFailed();
        } else {
            // This is an ERC721 transfer.
            // The `amount` parameter is ignored (implicitly 1).
            // `safeTransferFrom` is used for security, and our `nonReentrant`
            // guard on `claim()` protects against reentrancy attacks.
            IERC721(tokenContract).safeTransferFrom(address(this), to, tokenId);
        }
    }

    /**
     * @dev Overrides the `_msgSender()` from `ERC2771Context` to enable
     * meta-transactions. This is the heart of our gasless support.
     *
     * Why do this? Because we're also inheriting from other contracts (ReentrancyGuard, IAirdrop) and Solidity requires you to explicitly choose which parent's `_msgSender()` to use when there's potential ambiguity.
     */
    function _msgSender() internal view override(ERC2771Context) returns (address) {
        return ERC2771Context._msgSender();
    }
}

Dissecting the Thoughtful Design
This contract is more than just a piece of code; it's a system designed for trust. Let's look at the key decisions.

Enabling Gasless Claims Enabling ERC-2771 is a deliberate choice made at deployment.

A. Inheritance: We inherit from OpenZeppelin's ERC2771Context.

contract MerkleAirdrop is IAirdrop, ERC2771Context, ReentrancyGuard {...}

B. The Constructor: We tell the contract the address of the one-and-only trustedForwarder it will ever listen to.

constructor(
    bytes32 merkleRoot,
    address trustedForwarder
) ERC2771Context(trustedForwarder) {
    MERKLE_ROOT = merkleRoot;
}

The Core: _msgSender() vs. msg.sender This is where the magic happens. The ERC2771Context contract provides a function: _msgSender().

Here is a simplified view of what it does:

It checks, "Is the msg.sender (the gas payer) my trustedForwarder?"
If YES: It knows this is a meta-transaction. It reads the real sender's address from the end of the calldata and returns it.
If NO: It knows this is a normal transaction. It simply returns the msg.sender as usual.

This provides a single, reliable function that transparently handles both gasless calls and regular calls.

Look at our claim function's authorization check. It doesn't use msg.sender. It uses _msgSender():

// 3. (Authorization) Check that the sender is the rightful claimant.
// This is the core of our ERC-2771 integration.
address sender = _msgSender();
if (claimant != sender) {
    revert MerkleAirdrop_NotClaimant(claimant, sender);
}

With this in place:

If Alice calls claim() directly and pays gas:
- _msgSender() returns Alice.address.
- The check passes.
If Bob the Relayer calls via the Trusted Forwarder:
- _msgSender() returns Alice.address.
- The check passes. We have successfully separated the gas payer from the authorizer.

A Note on the override You'll notice this specific function at the end of the contract:

function _msgSender() internal view override(Context, ERC2771Context) returns (address) {
    return ERC2771Context._msgSender();
}

This may look redundant, but it's essential for clarity and correctness in Solidity.

Our contract inherits from both ERC2771Context and ReentrancyGuard. ReentrancyGuard also has a dependency on _msgSender() (via the Context contract). Solidity sees this "ambiguity" (which _msgSender should I use?) and requires us to be explicit.

Here, we are being deliberate: "When I call _msgSender(), I am explicitly stating that I want to use the version provided by ERC2771Context." It's a hallmark of excellent, precise engineering.

Beyond Gasless: Other Pillars of Trust A reliable contract is secure in all aspects. Thoughtful design extends beyond one feature.
Checks-Effects-Interactions: We mark the claim as used (claimedBitmap.set(index)) before we make the external call (_dispatchToken). This is a fundamental pattern to prevent reentrancy attacks.
Gas-Griefing Protection: We enforce a MAX_PROOF_DEPTH. This prevents an attacker from sending a valid but excessively long proof designed to waste gas and block others.
On-Chain Hashing: We never trust the client to provide a leaf hash. We reconstruct it on-chain (_hashLeaf(...)) to ensure the proof is for the exact data we expect.
Safe Hashing: We use abi.encode instead of abi.encodePacked in our hashing function. encodePacked can be ambiguous and lead to collisions; abi.encode is safer. This is a small, thoughtful choice that enhances reliability.

Conclusion: Engineering with Purpose
ERC-2771 is more than a technical standard; it's a design philosophy. It empowers us to build thoughtful, human-centered applications that remove the greatest point of friction in Web3: the gas fee.

By combining this standard with other principles of secure and reliable design, we can build systems that users can truly trust.

Let's build something you can trust with clarity, purpose, and excellence.

Thanks for reading! If you found this article thoughtful and reliable, I'd appreciate a like or a comment.

You can find the full GitHub repo for this project here: https://github.com/obinnafranklinduru/tailored-airdrop/blob/main/src/MerkleAirdrop.sol

To see more of my work on secure and efficient on-chain systems, feel free to visit my portfolio at https://binnadev.vercel.app

Why I Rebuilt My Developer Portfolio Around Three Core Values (Reliability, Thoughtfulness, and Excellence)

Obinna Duru — Wed, 05 Nov 2025 17:41:49 +0000

A reflection on designing a portfolio that practices the same principles as the code I write.

For the past few days, I've been "vibe coding" a new portfolio. But I didn't just want to build a resume; I wanted to build a digital extension of my core philosophy.

As a Smart Contract Engineer, I work with systems that handle real value. When you're building systems that handle real value, trust is everything. That's why I've centered my entire professional brand on three core values: Reliability, Thoughtfulness, and Excellence.

It felt hypocritical to have a brand built on these values if my own website didn't live up to them. So, I decided to build a new digital home from scratch, using those same three values as my guide.

🟣 Reliable: A "Living" Portfolio

My old site was a chore to update. This new one is reliably current.

My /work page is now a live feed from the GitHub API.
My /writing page pulls directly from my Dev.to API.
If I push new code or publish a new post, my site updates automatically.

No manual steps-just a single, reliable source of truth.

🟡 Thoughtful: A Human-Centered Experience

A "thoughtful" site has to work for everyone. I obsessed over the details to make it human-centered:

It's built to be accessible, with clean typography and proper color contrast.
The design is minimal, elegant, and precise, with no clutter to get in the way.
I also implemented a complete JSON-LD schema - a technical way of giving search engines a clear, structured map of who I am, making the site more discoverable and "thoughtful" for all.

🔵 Excellent: The Polish and Performance

Excellence is in the craft.
This isn't a template, it's a hand-built site using Next.js 14, TypeScript, and Server Components.

It scores 95+ on Lighthouse for performance and accessibility, and every interactive element from buttons to project cards has its own subtle, deliberate motion.

It feels fast, balanced, and complete.

This project was both a vibe and a statement.
It's more than a portfolio, it's my new digital home.

Let me know what you think.
Let's build something you can trust 🤝.

👉 Check it out: https://binnadev.vercel.app