Forem: Obinna Duru

The Brief for the Judge: Writing Audit-Ready Documentation

Obinna Duru — Tue, 28 Apr 2026 17:00:00 +0000

We have spent the last four posts building MilestoneCrowdfundUpgradeable protocol. We architected an upgradeable proxy, designed a mathematically rigorous escrow engine, fuzz-tested its invariants, and locked the doors against reentrancy attacks. We built a fortress.

But there is one final step. A secure fortress is incredibly dangerous if you don't leave behind a blueprint explaining exactly how the traps and locks are supposed to work.

Most developers hate writing documentation. In Web2, bad documentation means a new developer joins your team and spends three days figuring out an API endpoint instead of one hour. Frustrating, expensive, recoverable.

In Web3, bad documentation is catastrophic. When you hand your code to a security auditor, bad documentation means they might misunderstand the intended behavior of a function. They might classify a deliberate design choice as a vulnerability, forcing you to waste weeks fixing a non-issue. Worse, they might see a real bug, assume it was your intended logic, and let it pass into production where user funds get drained.

In this final post, I want to share exactly how I approached documenting MilestoneCrowdfundUpgradeable from NatSpec comments to architectural READMEs and why I believe documentation is the most underrated security tool in Web3.

The Mindset: Preparing the Brief

When I prepare a protocol for an audit, I think of the documentation as the brief I am handing to a judge before a trial.

The auditor is the judge. The code is the evidence. But without the brief, without the written explanation of intent, the documented invariants, and the explicit threat model, the judge is left to interpret the evidence alone. And interpretation without intent is where dangerous misreadings happen.

But here is the deeper truth: documentation isn't just for auditors. It is for the version of you that comes back to this codebase in six months after working on three other projects. That person has forgotten everything. The comments and the threat model are the only things standing between future-you and a catastrophic misunderstanding of your own protocol.

My rule is simple: If I have to think for more than five seconds about what a piece of code is doing, that piece of code needs a comment. Not because the code is bad, but because the next person reading it shouldn't have to spend those same five seconds. In a paid audit, those five seconds across a thousand lines become expensive hours of confusion.

NatSpec: Before, During, and After

Solidity uses a comment format called NatSpec (Ethereum Natural Language Specification). My approach to writing it happens in three distinct phases:

1. Before (The Specification)
I write the @notice and @param descriptions before I write the function body. This forces me to articulate what the function is supposed to do in plain English before I write a single line of logic. If I cannot describe it clearly in one sentence, I do not understand it well enough to code it yet. The comment becomes the specification; the code is just the implementation.

2. During (The "Why")
While writing the body, I add inline comments at critical decision points. In the last post, we looked at this exact code block:

// CEI: Effects - Update the ledger first, before money moves!
_pledges[_id][msg.sender] = 0;

Any competent developer can read _pledges[_id][msg.sender] = 0 and know what it does. What they cannot know without a comment is that this line is here specifically to prevent a reentrancy attack. My personal rule: The code says "what". Only a comment can say "why".

3. After (The Edge Cases)
After the function is complete, I write the @dev block. This is where I document the non-obvious: the edge cases I considered and rejected, the invariants this function must maintain, and the assumptions that must be true for it to be safe.

The Power of Visual State Machines

A smart contract is a state machine. It has states (Fundraising, Succeeded, Failed, Abandoned) and transitions between those states (finalize, haltCampaign).

You can write all of that in prose, but the human brain does not reason about state machines in paragraphs. It reasons about them visually. The moment I drew the state diagram for MilestoneCrowdfundUpgradeable using PlantUML, a massive gap became visible.

Looking at the diagram, I immediately noticed there was no direct transition from Fundraising to Abandoned. A campaign could only be Abandoned after it Succeeded. That was a correct design decision, you shouldn't be able to abandon a project that never even got funded but seeing it drawn forced me to go back and verify that the Solidity code actually enforced this explicitly. The diagram asked a question the code never explicitly answered.

Diagrams also communicate to people who cannot read Solidity. Your investors, your community, or a tokenomics specialist auditing your math might struggle with the raw code, but they can instantly follow a visual map.

The README Architecture

A lot of Web3 repositories just leave the default Foundry or Hardhat README file. Alternatively, they throw every piece of information into one giant, 3,000-word file.

One giant file is a red flag. It tells an auditor that the author did not think carefully about who would be reading it. I split the MilestoneCrowdfundUpgradeable documentation into specific hubs tailored to specific readers:

Protocol_Architecture.md: Written for the Auditor. Their primary question is: What is this protocol supposed to do, and what rules must it never break? This document answers that immediately.
Integration_Guide.md: Written for the Frontend Developer. Their primary question is: How do I call these functions correctly without breaking anything? They need the function signatures and error codes, not the threat model.
Incident_Response.md: Written for the Security Researcher. If they find a live vulnerability, their primary question is: Who has the authority to pause this, and how do I reach them right now? If they have to dig through installation instructions to find your emergency contact, you are wasting critical seconds during a hack.
Threat_Model.md: Written for the Skeptical Reviewer. This is the document most developers skip. It says: Here are the attacks we considered, here is why we are protected, and here are the residual risks we knowingly accepted. You cannot write a threat model without thinking like an attacker, and you cannot think like an attacker without finding things you missed.

A well-structured repository is a signal of engineering maturity. Before an auditor reads a single line of your Solidity, they have already formed a judgment about how seriously you take correctness based on your file structure.

The Hardest Part: Combating Drift

The hardest part is not writing documentation. It is keeping it true.

Code changes. Documentation does not change automatically. The gap between them is one of the most dangerous states a codebase can be in.

I experienced this directly. Early in the design of the fiat bridge, pledgeFiatOnBehalf was intended to apply a reduced platform fee. The NatSpec reflected that. Later, the stakeholder and I decided fiat pledges would be completely fee-exempt on-chain, with fees handled off-chain by Stripe.

I changed the code. I didn't immediately update the comment.

I caught it during a final review pass, but imagine if I hadn't. An auditor reading that comment would have expected fee logic that didn't exist, flagged its absence as a high-severity bug, and forced us to waste days in remediation meetings arguing over a phantom issue.

The discipline I developed from that experience is strict: Every time you change a function body, you update the NatSpec before you close the file. Not before you commit. Immediately. The comment is a structural part of the function, not a separate chore to do later.

The BinnaDev Takeaway

When a junior developer tells me, "My code is clean, it's self-documenting, I don't need to write a README," my response is always the same:

"Show me the part of your code that explains why you made that design decision."

Clean code tells you what. Only documentation tells you why. And in smart contract engineering, the why is where all the security lives. "Self-documenting code" makes sense in Web2 where the worst-case scenario is a confused colleague. It does not make sense in Web3 where the worst-case scenario is a misunderstood intent that costs your users everything they trusted you with.

Here is the practical test: If a professional auditor had to judge whether a specific line in your contract was an intentional design choice or a bug, would your code give them enough information to judge correctly without asking you a single question? If the answer is no, you need documentation.

And I will be completely honest with you on how I execute this practically.

English is not my first language. Documentation is fundamentally an asynchronous communication tool, you are writing for a stranger who cannot ask you a follow-up question, they have to wait for your response. In this context, a grammatical error doesn't just look careless; it creates genuine ambiguity. Did the developer mean this or that? To solve this, I use AI. Agile engineering tells us to prioritize working software over comprehensive documentation. That doesn't mean skip the docs; it means be smart about where your mental energy goes. The architecture, the invariant math, the security decisions, those required 100% of my focus. I used AI to help draft NatSpec suggestions and catch grammatical ambiguity so my thinking wasn't limited by the mechanics of expressing it in a second language. The ideas are mine entirely. The precision of communicating them is a collaboration.

Your code being clean means you are a careful developer. Your protocol being documented means you respect the people who will put their money into what you built. Both are required. You have the tools. Use them.

This concludes our five-part journey building the MilestoneCrowdfundUpgradeable protocol. From upgradeable proxies to defensive math, stateful fuzzing, reentrancy guards, and audit-ready documentation.

I hope this series has given you a real-world look at what security-first Web3 engineering actually looks like. Keep building, stay paranoid, and write excellent code.

Thinking Like an Attacker: The Airbags and Seatbelts of Smart Contract Security

Obinna Duru — Tue, 28 Apr 2026 07:00:00 +0000

In our last post, we built a mathematical proving ground using Foundry. We used stateful fuzzing to prove that the rules of our MilestoneCrowdfundUpgradeable protocol work exactly as intended.

But testing only proves that the contract behaves correctly when people follow the rules. What happens when someone actively tries to break them?

In Web2, when you think about security, you think about the perimeter. Who can get in? You build firewalls, you require authentication, you set up rate limiting. The attacker is outside the system, trying to break down the door.

In Web3, there is no perimeter. Your contract is public. The state is public. Every single function is readable by anyone on earth the moment you deploy it. The attacker is not trying to get past a wall, they are standing inside the room with you, reading your rulebook, looking for a sentence that contradicts itself.

So, my security-first mindset when I sit down to write Solidity is this: I am writing rules for a system that a brilliant, motivated, financially incentivized adversary will study longer and harder than I wrote it.

In this post, I want to show you exactly how I design against those adversaries. We are going to look at the most infamous hack in Web3 history, how to prevent it using the golden rule of smart contracts, and the real-world edge cases I had to actively design around.

The Refund Kiosk Glitch

To understand the most dangerous exploit in smart contracts, you don't need to understand code yet. You need to understand the refund kiosk glitch.

Imagine a store installs a new, automated self-service refund kiosk. It works like this:

You scan your receipt.
The machine dispenses your cash.
The machine marks your receipt as "refunded" in the database.

A clever person notices something. Between step 2 and step 3, there is a processing gap: a brief moment while the database updates.

So, the attacker builds a device and physically attaches it to the kiosk's cash dispenser slot. When cash drops into the tray, the weight of the notes triggers a pressure sensor inside the device, which automatically scans the receipt again immediately.

The attacker does not press any buttons. The act of receiving cash is itself the trigger for the next scan.

The kiosk checks the database: "Is this receipt already refunded?" The database still says no, because step 3 hasn't happened yet. So the kiosk dispenses again. Cash drops. The pressure sensor fires. The receipt scans again. The database still says no. It dispenses again.

This loop continues until the machine is completely empty. Nobody held anyone at gunpoint. The machine was following its own rules perfectly, it checked the ledger every single time before it paid. It just checked a ledger that was always one step behind reality.

The fix is incredibly simple. You just change the order of operations at the kiosk:

Scan your receipt.
Mark it as refunded in the database immediately.
Now, dispense the cash.

Now, when the cash drops and the pressure sensor fires a second scan, the kiosk checks the database, sees it is already refunded, and dispenses nothing. The loop never starts. By updating the internal record before handing over the cash, we close the exploitation gap entirely.

In smart contract engineering, this fix is called Checks-Effects-Interactions (CEI).

Check: Does this user have a valid claim?
Effect: Zero their balance in the ledger right now, before a single coin moves.
Interaction: Now, send the money.

Reentrancy: The Kiosk on Ethereum

Now that you understand the kiosk glitch, you already understand Reentrancy. Because Reentrancy is exactly that glitch, running on a blockchain.

In Ethereum, when your smart contract sends ETH to an address, if that address belongs to another smart contract, it can execute code the exact moment it receives the ETH. That receiving code is called a receive() function.

That receive() function is the pressure sensor. The attacker writes it once, deploys their contract, and the blockchain executes it automatically the moment ETH arrives. They do not manually trigger anything. The callback is a feature of how ETH transfers work, turned into a weapon.

Here is what the attacker's contract looks like:

contract Attacker {
    MilestoneCrowdfund public target;

    // The pressure sensor: When this contract receives ETH, 
    // it immediately calls claimRefund again, before the first call finishes!
    receive() external payable {
        target.claimRefund(campaignId);
    }

    function attack() external {
        target.claimRefund(campaignId);
    }
}

If we sent the money before updating our internal ledger, this attacker would drain our entire protocol in a single transaction. But because we use the Checks-Effects-Interactions pattern, look at the exact order of the claimRefund function inside MilestoneCrowdfundUpgradeable:

// 1. CHECKS: Does the user have a valid claim?
uint256 userPledge = _pledges[_id][msg.sender];
if (userPledge == 0) revert MilestoneCrowdfund__NoContribution();

// 2. EFFECTS: Update the ledger first, before money moves!
_pledges[_id][msg.sender] = 0;

// 3. INTERACTIONS: Now the money moves.
(bool success,) = payable(msg.sender).call{value: refundAmount}("");

By zeroing _pledges[_id][msg.sender] before the ETH moves, every malicious reentrant call finds a zero balance and reverts immediately. The ledger is never one step behind.

As a second line of defense, I also use OpenZeppelin's nonReentrant modifier. It works by setting a lock flag at the start of the function. Think of it as a door that locks behind you the moment you step inside. If the malicious receive() function tries to call claimRefund again, it slams into that locked door, and the entire transaction instantly reverts.

CEI makes the contract logically correct. nonReentrant makes it mechanically impossible to reenter. I tell every junior developer: do not choose between them. Use both. CEI is the airbag. nonReentrant is the seatbelt. You want both in the car.

The Real Edge Cases I Had to Design Around

Security isn't just about stopping hackers; it's about mitigating the risks of your own design choices. There were two specific edge cases I had to actively design around.

1. The Live Fee Rate
In MilestoneCrowdfundUpgradeable, the platform fee (defaultFeeBps) is a global variable that the owner can change at any time. This means two donors to the exact same campaign could pay different effective fees if the owner changes the rate between their pledges.

Why design it this way? Because the stakeholder explicitly requested the flexibility to run dynamic fee promotions. I immediately flagged the vulnerability to them: what if a compromised owner key raised the fee to 5% right before a massive whale pledge, and then immediately lowered it back? This would silently skim thousands of dollars from a single donor, and unless you were watching the transaction pool in real-time, it would be almost invisible.

I agreed to the stakeholder's requirement, but only with a strict mitigation strategy. The defense here isn't in the Solidity code, it is in the governance architecture. The owner is strictly documented as an Admin Multisig wallet. A single compromised key cannot change the fee unilaterally. The system around the code must be designed with the same rigor as the code itself.

2. The Dust Sweep
When dividing milestones by percentages, integer division always leaves a tiny fraction of a cent (wei) permanently locked in the contract. To prevent this "dust" from being lost forever, my contract uses a special code path for the final milestone:

if (c.milestonesReleased == c.milestoneCount) {
    amountToRelease = c.totalRaised - c.totalWithdrawn;
}

It simply sweeps whatever is left. But I had to ask myself rigorously: Can this sweep ever release MORE than it should? The mathematical guarantee that it cannot is my invariant: totalWithdrawn <= totalRaised. That is precisely what that same 4,495-second fuzz run from the last post was verifying. The fuzz test isn't decoration; it is the mathematical evidence that this final sweep is safe.

The BinnaDev Takeaway

If you are a junior developer about to deploy your first contract that holds real ETH, here is my ultimate advice to you:

Do not deploy until you can answer this question about every function that sends money: "What happens if the recipient is a malicious contract?"

Not a normal wallet. A smart contract. With a receive() function you did not write, controlled by someone who wants your users' funds, with a pressure sensor already wired and waiting.

If you cannot answer that question confidently for every single external call in your codebase, you are not ready to deploy. Go back and apply the Checks-Effects-Interactions pattern to every function that moves value. Add nonReentrant to every function that moves value. Then ask the question again.

The developers who get hacked are not the ones who don't know about reentrancy. They are the ones who know about it in theory, but did not sit down with their own code and ask that exact question. Knowledge without application is not protection.

Read your own code as if you are the attacker. The moment you find something that makes you uncomfortable as the attacker, you have found something to fix as the engineer. If you want a structured baseline for this evaluation, I highly recommend reading Trail of Bits' excellent post, Can You Pass the Rekt Test? It is a mandatory checklist for any serious Web3 engineering team.

Sleep comes after that review. Not before.

We have architected the protocol, proven the math, and secured the vault. But a secure protocol is useless if no one knows how to safely interact with it. In our fifth and final post, we are going to talk about the most underrated skill in Web3: Writing Audit-Ready Documentation.

Stop Guessing, Start Proving: A Guide to Stateful Fuzzing in Foundry

Obinna Duru — Mon, 27 Apr 2026 15:55:29 +0000

We are building MilestoneCrowdfundUpgradeable: a smart contract that holds donor funds in escrow and releases them only when real-world milestones are verified. In our last post, we designed the engine for this protocol. We built a theoretical fortress guarded by strict mathematical laws.

But in Web3, a theoretical fortress isn't good enough. If you write a web app and it has a bug, a button doesn't work. If you write a smart contract and it has a bug, people lose their life savings. Testing isn't an afterthought; it is a matter of life or death for your protocol.

To test this protocol, I didn't just write a few scripts to see if the functions worked. I built a mathematical proving ground. In this post, I want to show you exactly how I did that. We are going to talk about why I switched to Foundry, how to use a "fuzzer" to find your blind spots, the magic of Ghost Variables, and the hardest lesson I learned about testing state machines.

The Shift: Why I Chose Foundry Over Hardhat

When I write tests in Hardhat, I am writing JavaScript that talks to a Solidity contract. There is a translation layer between my brain and the blockchain. I find myself fighting JavaScript's async/await, weird big-number edge cases, and ABI encoding at the exact same time I am trying to think about protocol correctness. It's exhausting.

Foundry breaks that barrier. In Foundry, your tests are written in Solidity. The EVM (the actual engine that runs Ethereum) is the test runtime. That means there is no JavaScript middleman translating your code. If I want to pretend to be a user named Alice, I just write vm.prank(alice). If I want to fast-forward time by 30 days, I write vm.warp(block.timestamp + 30 days). It reads like pseudocode.

But the single biggest reason I switched, the one that changed how I think about testing entirely is exactness. In Hardhat, you approximate gas. In Foundry, the gas numbers in your test output are the exact gas numbers you will see on mainnet. When you're designing a crowdfunding protocol where everyday donors are paying for every pledge call, that exactness matters enormously.

Hardhat is an incredible tool for deployment and scripting, but Foundry was built from the ground up for testing. That is not a knock on Hardhat, it is just not the same tool.

Stateless Fuzzing: Why Random Beats Hardcoded

Here is the problem with writing pledge(100) in your test suite. Your brain picked the number 100. Your brain also wrote the smart contract. So your test is testing your own assumptions, not the contract's actual behavior. You have the same blind spots on both sides of the assertion.

Stateless Fuzzing breaks that loop. A fuzzer is a robot that throws thousands of random, chaotic inputs at your contract to see what breaks.

For example, I wrote a function to calculate the platform fee (_calculateFeeAndNet). The obvious test is: gross = 1000, fee = 5%, expect net = 950. That passes. Fine.

But what does the Foundry fuzzer actually throw at it?

gross = 1, fee = 4.99%. (Does integer division correctly floor the fee to zero, leaving the full amount as the net?)
gross = type(uint256).max. (Does it trigger an overflow crash before the math finishes?)
fee = 0. (Does the contract actually return (gross, 0), or does it accidentally return (0, 0)?)

None of those are inputs I would naturally write. The fuzzer doesn't have my assumptions. That's its superpower.

This was crucial for my Basis Points (BPS) math. I wrote a helper to divide 10,000 BPS across n milestones. I could have hardcoded an array of 3 milestones and called it done. Instead, the fuzzer randomly varies n on every single run. Eventually, it tries n=1 (a single milestone getting 100%) and n=20(20 milestones, each getting ~500 BPS, with the last one absorbing all the mathematical rounding dust). Those extreme edge cases stress the math in ways a handwritten array never would.

Stateful Fuzzing & Ghost Variables: The Bank Auditor

Stateless fuzzing tests one function at a time. But a crowdfunding contract isn't a calculator, it's a state machine. The bug is almost never in a single function in isolation. It's in the sequence. pledgeETH is fine. withdrawMilestone is fine. But what happens if the sequence is pledgeETH -> setFee -> pledgeETH -> finalize -> withdrawMilestone? That is where the accounting drifts.

To test sequences, we use Stateful Fuzzing.

To explain how this works, imagine you are a Bank Auditor. You want to verify that a bank teller never gives out more money than was deposited. You could stand at the counter and check after every single transaction. But the teller's official ledger is locked inside a vault you can't open. You can only see the cash they hand to customers.

So, you bring your own notepad. Every time someone deposits $100, you write "+$100" on your notepad. Every time someone withdraws, you write "-$50". At the end of the day, your notepad says the vault should hold exactly $50. If the vault actually holds $40, something went wrong in the sequence of the day's transactions.

In my Foundry tests, that "notepad" is called a Ghost Variable.

The actual pledge ledger inside my smart contract (_pledges) is private. The test suite can't read it easily. So, I built a Handler contract that acts as the Auditor. It carriesghost_netPledge, its own running tally of what the contract should contain. Every time a random pledge succeeds, the handler writes it down. Every time a refund succeeds, it zeroes that entry.

At the end of thousands of random actions, the test asks: Does the real smart contract match my notepad? Imagine a scenario where Alice pledges 1 ETH, but a bug prevents the platform fee from being deducted. My Ghost Variable notepad records 0.95 ETH (the net), but the contract's getPledge() returns 1.00 ETH. The moment they diverge, the invariant fires. The fuzzer stops and prints the exact 12-call sequence that broke the math. That sequence is my counterexample. That's the bug report.

The Struggle: 4,495 Seconds of Patience

Here is the part nobody talks about in tutorials.

You can see it in the screenshot from my terminal. 4,495 seconds. That is over an hour and fifteen minutes of my laptop running at full capacity just to complete one single test run.

That number tells the real story of stateful fuzzing. My fuzzer ran this long because of the rigorous constraints I set. Here is exactly how I configured it. runs is how many random sequences the fuzzer invents, depth is how many calls deep each sequence goes, and the seed ensures the run is mathematically reproducible so I can track down bugs:

[invariant]
runs = 1000
depth = 300 
fail_on_revert  = false
call_override_addr = false

[fuzz]
runs = 1000
max_test_rejects = 65536
seed = "0x63726f776466756e64"

The fuzzer is not running one test, it is inventing thousands of random call sequences, executing them, and checking whether the math breaks. That computational cost is the point. You are paying for thoroughness with time.

But the truly humbling part is the feedback loop.

When you write a normal unit test and something breaks, you fix it and rerun it in seconds. With a stateful fuzz suite, the cycle feels like this:
Find a bug -> fix the contract -> wait 75 minutes -> find another bug -> fix -> wait another 75 minutes.

Now, to be fair to Foundry, it does provide a lifesaver here. When a stateful fuzz run fails, Foundry gives you the exact seed and call sequence, allowing you to replay just that one failed scenario in seconds without having to rerun the entire 75-minute suite. But the broader lesson remains.

You learn very quickly to think carefully before you type. Every structural change carries a heavy price tag in computational validation. That constraint made me a more deliberate engineer. I stopped making small speculative fixes and started reasoning through the problem fully on paper before touching the code.

The Coverage Illusion

Now look at the numbers in that screenshot more carefully.

MilestoneCrowdfundUpgradeable.sol - 100% line coverage, 100% function coverage.

A junior developer sees that and thinks: We are done, the protocol is safe. I want to push back on that directly. 100% coverage does not mean 100% secure. Not even close.

Coverage only tells you that the fuzzer visited every line. It does not tell you whether the mathematical rules governing those lines can be broken by a clever sequence of calls. A line can be executed ten thousand times and still contain an accounting bug that only surfaces on the ten-thousand-and-first call in a specific order.

This is why the invariants matter more than the coverage number. The invariants are the rules that must never break:

totalWithdrawn must never exceed totalRaised, otherwise, the creator is stealing from future refund claimants.
sum(milestoneBps) must always equal 10,000, otherwise, the math will trap dust in the contract or fail to release the full amount.
totalWithdrawn + totalRefunded must never exceed totalRaised, otherwise, the contract is paying out money that was never deposited, meaning it has become completely insolvent.

If those rules hold across thousands of random sequences, the protocol math is battle-tested. If coverage is 100% but an invariant breaks, you have a vulnerable protocol with a false sense of security. I would rather have 80% coverage and unbreakable invariants than 100% coverage and uninspected state transitions.

The Advice I Would Give My Fellow Dev

Stop writing tests that only ask "did this function return the right number?"

Start writing tests that ask "can this sequence of 50 random actions, executed by strangers in any order, break the rules this protocol was built on?"

Unit tests are essential, do not skip them. But they test your assumptions. The fuzzer tests your blind spots. Once you understand state machines and invariants, you stop guessing whether your protocol is safe and start proving it. That shift in thinking from hoping the code is correct to mathematically verifying it is the difference between a developer and an engineer.

The argument for trusting your test suite is never complete until you prove it works. Before I trusted my invariants, I deliberately broke my own contract. I went into pledgeETH and changed c.totalRaised += net to c.totalRaised += gross. I ran the suite. Instantly, Invariant 6 fired and the test failed. That is the difference between claiming your alarm system works and proving it by tripping it yourself.

The 4,495 seconds were worth every one.

Your protocol can pass every invariant and still be drained in a single transaction. In the next post, we look at how.

From Promises to Proof: Designing a Defensive Escrow Protocol

Obinna Duru — Mon, 27 Apr 2026 07:00:00 +0000

In the last post, we looked at how to make smart contracts upgradeable safely. But an upgradeable proxy is just an empty building. Today, we are walking inside the building to look at the engine.

If you are new to Web3, you might wonder why we even need smart contracts for crowdfunding.

Think about traditional crowdfunding platforms like Kickstarter. You trust the creator, you send them your money upfront, and you hope they deliver. Or, think about basic crypto transfers: you send ETH directly to a developer's wallet.

Both scenarios have a simple, critical flaw: you are giving away 100% of your money based on a promise. There is no enforced rule that says, "You only get paid if you actually do the work." If the creator vanishes after taking your money, you are out of luck.

What I wanted to fix with the MilestoneCrowdfundUpgradeable protocol wasn't fundraising. It was execution trust.

The Mental Model: What is a Defensive Escrow?

I framed the architecture around a concept I call a Defensive Escrow.

Instead of sending money directly to a person, you send it to a smart contract. Think of the smart contract as an unbreakable, unbiased robot middleman. The robot locks the money in a vault. It only releases the funds chunk by chunk as the creator proves they've completed specific milestones.

If the creator fails or disappears, the robot protects you automatically by returning whatever is left in the vault.

Here is how I designed the mechanics to make that happen.

The Math Problem: Why 10,000 Basis Points?

When you build financial systems in Solidity, you quickly learn one thing: the Ethereum blockchain hates decimals.

If you try to divide $100 by 3, a normal computer gives you $33.3333... But Solidity doesn't do fractions well. Those leftover .3333 fractions (we call them "dust") can get permanently trapped in the contract. Over time, the math breaks.

To remove this ambiguity, I standardized everything using a financial concept called Basis Points (BPS). In this system, 10,000 BPS is exactly equal to 100%.

Instead of giving a creator a fixed amount of tokens, we give them slices of a pie.

Phase 1 is 4000 BPS (40% of the pie).
Phase 2 is 4000 BPS (40% of the pie).
Phase 3 is 2000 BPS (20% of the pie).

Why is this pie method so important? Stretch goals.

Imagine a charity sets a goal of $10,000, but the campaign goes viral and raises $50,000. If our code said "Give the creator exactly $4,000 for Phase 1," the contract would get confused by the extra $40,000 sitting in the vault.

But because our milestones are percentages tied to the total amount raised, the math adapts automatically.

40% of $10,000 is $4,000.
40% of $50,000 is $20,000.

The pie gets bigger, but the sizes of the slices stay exactly the same. The code doesn't break.

Graceful Failure: The "Abandoned" State

Most smart contracts only understand black and white: Success or Failure.

If the campaign fails to hit its goal, the robot opens the vault and gives everyone a 100% refund. Easy.

But what if the campaign succeeds, the creator takes 40% of the funds to start Phase 1, and then they vanish? You cannot pretend nothing happened. 100% of the money isn't there anymore.

This is where the "Defensive" part of the Defensive Escrow kicks in. I added a state called Abandoned.

If a creator goes rogue, an Admin can press a haltCampaign button. The robot permanently locks the vault.

The concept is simple: you are refunded based on the work that was never unlocked. If you pledged 10 ETH, and the creator ran away after taking 40%, the robot mathematically guarantees you get your remaining 6 ETH back.

This turns a "crypto scam" into a structured, safe process. There is no emotional arguing over who gets what. The math just settles the difference.

The Fiat Bridge: Bringing Web2 to Web3

Most Web3 systems make a fatal assumption: they assume every user already has a crypto wallet and knows how to pay gas fees. That assumption kills adoption.

Now, you might be thinking: "Wait, Obinna, don't we already have smart accounts where users can log in with their Gmail? Aren't there easy fiat on-ramps and off-ramps today?"

Yes, absolutely. The Web3 ecosystem has made massive strides with Account Abstraction and embedded wallets. However, I still chose to architect a direct platform-to-fiat bridge called pledgeFiatOnBehalf.

Why? Because true adoption requires absolute user flexibility. Some people simply do not want to go through a crypto on-ramp or manage a smart account even a hidden one. They want to type their credit card into a familiar website and be done in 30 seconds, remaining entirely Web2-native. By building a custodial bridge, we allow those users to participate natively, while their economic support is still mathematically secured in our smart contract.

If Bob pays $100 with a credit card on our website, our secure backend sees the payment. Then, our own "Platform Wallet" interacts with the smart contract, depositing $100 worth of crypto into the vault on Bob's behalf.

We act as a custodian for Bob. The messy credit card logic stays entirely off-chain, while the blockchain remains the ultimate, pristine source of truth for the project's funding.

The Trust Model: "Wait, isn't this centralized?"

If you have been reading closely, you might have noticed a recurring theme: an Admin or Platform wallet has the power to approve milestones, press the "Halt" button, and bridge fiat payments.

A developer might look at this and ask, "Wait, Obinna, isn't this centralized?"

It is a great question. Yes, there is a human element. But having an administrative role is not the same as having total system control. To understand why, you need to understand the concept of an Invariant.

In smart contract engineering, an Invariant is a mathematical law written into the code that can never, ever be broken. Not even by the creator. Not even by the Admin.

Here is the distinction:

What the Admin CAN do: They can pause the protocol, tell the robot a milestone is finished, or press the "Halt" button to trigger refunds.
What the Admin CANNOT do: They cannot withdraw user funds to their own wallet. They cannot bypass the milestone math. They cannot rewrite the refund logic.

The real protection is not governance, it's the strict math constraints written into the robot's code.
The trust model is simple: Humans can trigger states, but they cannot violate the financial laws of the system. That is the boundary.

The BinnaDev Takeaway

If I step back and summarize the architecture, this isn't just "crowdfunding with milestones."

It is a system where capital is locked into predictable, mathematical rules. Failure is not a disastrous rug-pull; it is a structured, mathematically safe process. Fiat and crypto are unified so anyone can participate on their own terms.

Or, to put it in one line:

Immutability handles correctness. Milestones handle trust. Invariants handle safety.

Now that we have written the rules of the protocol, how do we prove they actually work? How do we know a hacker can't break the math? In the next post, we are going to dive into Foundry Testing. I'll show you how I test these invariants to mathematically prove they hold up against any attack.

Immutability by Default, Upgradeability by Necessity: Lessons from a Crowdfunding Protocol

Obinna Duru — Sat, 25 Apr 2026 01:09:08 +0000

Smart contracts handle real value, so I believe every line of code should communicate trust.

When you first start learning Solidity, you are taught one golden rule: smart contracts are immutable. Deploying a contract is like launching a rocket into space, once it leaves the launchpad, you can't easily change the wiring. If there is a bug, the code is set in stone.

But recently, while building MilestoneCrowdfundUpgradeable: an onchain escrow protocol verified on Polygon. I hit a classic Web3 crossroads.

My stakeholder had a very practical requirement: flexibility. We knew we had future upgrades planned for the protocol, but we couldn't ask our users to interact with a new contract address every single month. That is a terrible user experience and a quick way to erode trust. We needed a single, reliable entry point for users, while maintaining the ability to upgrade the underlying logic.

We needed an upgradeable contract.

In this post (the first of a five-part series), I want to sit down with you and share exactly how I approached Upgradeability. If you are a beginner or intermediate developer trying to wrap your head around proxies, storage collisions, and initialization traps, this post is for you.

What Actually is a Proxy? (The Restaurant Analogy)
Before we talk about how to upgrade, we have to understand the architecture. How do you change code that is supposed to be unchangeable?

You split the contract into two pieces. I like to explain it using a restaurant analogy:

The Proxy (The Building & Cash Register): This contract has a permanent address. Users only ever interact with this contract. It holds all the money (ETH) and all the data (state).
The Implementation (The Kitchen Staff & Recipe): This contract holds the actual logic (the code for pledge(), refund(), etc.).

When a user sends money to the Proxy, the Proxy uses a special Ethereum command called delegatecall. It basically says to the Implementation: "Hey Kitchen, borrow my ingredients and tell me how to process this order, but leave the money in my cash register."

If we find a bug in our recipe, the Admin simply deploys a brand new Implementation contract (a new Kitchen Staff), and tells the Proxy to start asking them for instructions instead. The building address and the cash register never change.

There are a few ways to build this. I chose a pattern called UUPS (Universal Upgradeable Proxy Standard) via the OpenZeppelin library.

Without getting too bogged down in jargon, older patterns (like Transparent Proxies) put the "upgrade manager" in the Proxy itself. UUPS puts the "upgrade manager" in the Implementation contract. I chose UUPS because it makes the Proxy lightweight, which makes transactions cheaper (lower gas fees) for our users.

The Constructor Trap (And How to Get Hacked)

When you write a normal smart contract, you use a constructor() to set up your initial variables (like assigning the owner). Constructors run exactly once, during deployment.
But in a proxy setup, the Proxy deploys after the Implementation. The Proxy can't trigger the Implementation's constructor. So, the golden rule of upgradeability is: Do not use constructors. Use an initialize() function instead.

At first, it feels like you can just swap the words and move on. But here is the trap: The implementation contract is still a live contract sitting on the blockchain. Imagine you deploy your Implementation contract, and it has an initialize() function that sets the owner. Your Proxy connects to it and calls initialize(). Great! Your Proxy is the owner.

But what about the Implementation contract itself? It's just floating out there. If you don't lock it, a hacker can call initialize() directly on the Implementation contract, make themselves the owner, and potentially command it to self-destruct. If the Implementation is destroyed, your Proxy is permanently broken.

To prevent this, my approach is strict:

All protocol setup goes into initialize().
I immediately lock the Implementation contract using a special constructor.

/// @custom:oz-upgrades-unsafe-allow constructor
constructor() {
    // This locks the Implementation contract so no one can initialize it directly
    _disableInitializers(); 
}

From a mindset perspective: Assume attackers will interact with your implementation contract directly. Once you internalize that, locking it stops being a confusing "trap" and simply becomes part of your default security posture.

Storage Management: The Giant Spreadsheet

Upgradeable contracts are notorious for "storage collisions."

Think of smart contract storage like a giant, invisible spreadsheet. Row 1 is owner. Row 2 is totalRaised.

When you upgrade to Implementation V2, the Proxy still uses that exact same spreadsheet. If you accidentally write V2 so that a new variable called isCampaignActive is placed in Row 1, you just overwrote the owner! That is a storage collision, and it is catastrophic.

To prevent this, my approach is conservative and explicit:

Append-only storage: Never reorder variables. Never delete variables.
Storage Gaps: I use the classic uint256[50] private __gap; at the bottom of my contracts.

A storage gap is literally just claiming 50 empty rows at the bottom of your spreadsheet. If I ever need to add a new variable in V2, I take one row away from the gap (uint256[49] private __gap;) and add my new variable.

Why gaps instead of newer, complex patterns (like ERC-7201)? Because it's simple, battle-tested, and auditors easily understand it. Storage layout is not "code you can refactor"; it's "state you must preserve forever." Discipline is your real protection.

The Hardest Lesson: Hunting for Ghosts

The single most frustrating moment I had while setting up this project in Foundry (my testing framework) came down to one line of code.

In Web3, we use something called a ReentrancyGuard to stop hackers from double-spending money. Because I was building an upgradeable contract, I kept trying to import ReentrancyGuardUpgradeable.

It just wasn't there. Most older tutorials, blog posts, and AI tools told me to use the Upgradeable version, so it felt like I was doing something wrong.

What finally clicked was reading the source code of the newest OpenZeppelin version. I realized that the standard ReentrancyGuard no longer relied on a constructor. It used internal logic that worked perfectly fine behind a proxy. I didn't need an upgradeable version anymore; I could just use the normal one:

import { ReentrancyGuard } from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

The frustrating part wasn't the code, it was the mismatch between my old mental model ("everything must have an Upgradeable suffix") and reality (some contracts are now inherently proxy-safe).

It forced a deeper shift in how I work: I stopped coding from patterns, and started reasoning from first principles. Upgradeability isn't just about making a proxy; it's about understanding how every single tool you import behaves under the hood.

The BinnaDev Takeaway

If a junior developer asked me today, "Obinna, should I make my next project upgradeable?" my answer would be:

It depends but try not to use it unless you have a clear, defensible reason.

Upgradeability is not a free feature. You gain flexibility, but you introduce new attack surfaces and complexity. If you can ship your protocol as immutable, do that first. It gives you a simpler mental model, fewer failure modes, and it is vastly easier to secure.

Only reach for upgradeability if the system will hold significant user funds, has evolving logic, or needs long-term maintenance. At that point, upgradeability becomes a risk management tool, not a convenience.

My guiding principle is this: Immutability by default, upgradeability by necessity. If you can't clearly explain why it must be upgradeable, who controls the upgrades, and how users are protected, then you aren't ready to use it yet.

Deployment Update

The MilestoneCrowdfundUpgradeable contract has been successfully deployed on Polygon (Chain ID: 137), marking the transition from design and testing into a live, verifiable environment.

Here are the core deployment details:

Proxy Address: https://polygonscan.com/address/0xf83aaB5f1fAA1a7a74AD27E2f8058801EaA31393
Implementation Address: https://polygonscan.com/address/0x003e81b1b080029b87c728590c9bfec339180625

This deployment reflects the architectural decisions discussed earlier: a proxy-based upgradeable system with clearly defined control boundaries and fund flow roles. With the contract now live, the focus shifts from infrastructure to behavior, how funds move, how milestones are enforced, and how the protocol responds under real-world conditions.

In the next post, we'll dive into the actual mechanics of the MilestoneCrowdfundUpgradeable protocol itself. I'll walk you through how we designed the escrow, the math behind milestone-based releases, and the trust model that protects users if a creator decides to walk away.

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