DEV Community: Obinna Duru

Understanding Gas on the Blockchain: A Practical Guide Using Real Transactions

Obinna Duru — Mon, 26 Oct 2026 13:33:56 +0000

When I first encountered the concept of gas in blockchain, I understood on the surface that it measured computational work. However, I did not fully understand what that meant in practice, how gas is actually calculated under the hood, why transactions need gas limits, or how all of those numbers come together to form a transaction fee.

Reading high-level definitions is one thing, but opening a block explorer and staring at a raw transaction receipt is another. Where does a specific number like 49,785 or 152,492 gas come from? Why does a transaction that transfers 0 ETH or 0 MON still cost money? And what actually happens to the gas you don't use?

For me, the best way to truly grasp a technical concept--to the point where you can confidently explain it to someone else--is to connect the abstract math to a physical, real-world analogy and then test it against real data.

In this article, we are going to break down how gas works from the ground up. We will build a simple physical mental model, look at how the Ethereum Virtual Machine (EVM) counts work, and then inspect two real blockchain transactions: one where I interacted directly with a smart contract on Monad Testnet, and a second transaction hash I pulled from the Ethereum Sepolia Testnet explorer to see how the two networks compare.

Separating the Five Core Concepts

When people talk about "gas," they often lump several different things into one blurry idea of "the fee I pay." To make transaction receipts easy to read, we first need to separate five distinct concepts:

Gas: The unit used to measure the computational work required to process a transaction.
Gas Limit: The maximum amount of gas a transaction is allowed to consume.
Gas Used: The amount of gas the transaction actually consumed during execution.
Gas Price: The monetary rate (in cryptocurrency) paid per single unit of gas.
Transaction Fee (Gas Fee): The final amount of cryptocurrency paid for processing the transaction, calculated according to the network's rules.

These concepts are closely related, but they do not mean the same thing.

A Relatable Analogy: The Delivery Truck
Think of executing a blockchain transaction like hiring a delivery truck to drive across town and flip a switch at a warehouse:

Gas (The Work): Driving 15 kilometers up a steep hill physically requires 10 liters of fuel. Notice that "liters" measures physical effort, not money. Whether fuel is cheap or expensive today, the engine still burns 10 liters to climb that hill.
Gas Limit (Your Fuel Cap): Before the driver leaves, you hand them a fuel card authorized for a maximum of 12 liters. You are saying: "This trip should take 10 liters, so I am allowing up to 12 liters as a safety buffer. If the road is blocked and you burn all 12 liters before getting there, stop driving immediately."
Gas Used (Actual Consumption): The driver completes the trip and the engine actually burns 10 liters.
Gas Price (Price per Liter): At the pump today, fuel costs $2 per liter. Tomorrow, during heavy traffic demand, it might cost $4 per liter. The distance and effort didn't change, only the price per unit of fuel.
Transaction Fee (The Total Bill): The final payment calculated from the fuel and the price per liter.

With that picture in mind, let's briefly look at how the blockchain measures those "liters of fuel" under the hood.

Under the Hood: How Does the Blockchain Count Gas?

When you submit a transaction on an EVM-compatible blockchain, the network doesn't guess how hard your transaction worked. Instead, every tiny instruction the computer executes--called an opcode--has a fixed cost measured in gas:

The Base Cover Charge (21,000 Intrinsic Gas): Before the blockchain even opens a smart contract, every standard transaction costs a flat minimum of 21,000 gas. This covers the basic work of verifying your cryptographic signature, checking your account nonce, and updating your account balance.
Basic Math & Memory: Inside a smart contract, simple operations like adding two numbers together (ADD) cost just 3 gas.
Reading & Writing Permanent Storage: Updating the blockchain's permanent database is the heaviest work a transaction can do, because every node on the network has to store that state change. Reading a variable from permanent storage for the first time in a transaction (SLOAD) costs 2,100 gas. Writing a brand-new non-zero value into an empty storage slot (SSTORE from 0 to 1) costs 20,000 gas, while updating an already non-zero slot (SSTORE from 1 to 2) costs 2,900 gas.

As your transaction runs, an internal meter starts at 21,000 and adds up the exact cost of every instruction executed along the way.

Now let's see how this looks on two real transaction receipts.

Case Study One: Calling `increment()` on Monad Testnet

For our first case study, I interacted directly with a smart contract deployed on Monad Testnet by calling its increment() function.

Here are the exact details from the transaction receipt:

Field	Value
Network	Monad Testnet
Function Called	`increment()`
Transaction Status	Success
Transaction Value	0 MON
Gas Limit	49,785
Gas Used (as reported)	49,785
Gas Usage	100%
Gas Price	102.82 Gwei
Transaction Fee	0.0051188937 MON

Why Did a 0 MON Transaction Still Incur a Fee?

Notice that the Transaction value is 0 MON. My transaction didn't send any MON tokens to another person or contract, yet it still charged a fee of 0.0051188937 MON. Why?

In our delivery truck analogy, Transaction value is the cash you put inside an envelope to send to someone across town. Even if you send the driver with $0 in the envelope just to flip a switch at the warehouse, the truck still has to burn fuel to drive there and flip the switch.

Look at the Solidity contract behind increment():

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

contract Counter {
    uint256 public count;

    function increment() external {
        count = count + 1;
    }
}

This contract stores a number called count on the blockchain. Whenever someone calls increment(), the contract increases count by one (changing it from 0 to 1, or 1 to 2). Even though the code looks tiny, the blockchain still has to process the transaction, run the contract's instructions, read the current value of count, and write the updated number into permanent storage.

The transaction fee pays for that computational processing and state update, not for transferring currency.

How Was the Fee Calculated--And Why Was Gas Usage 100%?

On this receipt, the Gas limit was 49,785, and the Gas used, as reported was also 49,785:

Gas Usage Percentage = (49,785 ÷ 49,785) × 100 = 100%

And if we multiply the Gas limit (49,785) by the Gas price (102.82 Gwei):

$49,785 x 102.82 Gwei = 5,118,893.7 Gwei

Using the conversion of $10⁹ Gwei per 1 MON:

Transaction Fee = 5,118,893.7 ÷ 10⁹ = 0.0051188937 MON

This matches the displayed transaction fee down to the last digit.

But this raises an important question: Why does Monad calculate the fee using the Gas Limit, and why did the receipt report 100% gas usage?

Unlike Ethereum, which charges you based on the gas your transaction actually used after running, Monad charges based on the Gas Limit you declare upfront (and sets gasUsed equal to gasLimit on the top-level receipt).

To understand why, compare a supermarket checkout (Ethereum) with booking cargo on an airplane (Monad):

Ethereum (Supermarket Checkout): When an Ethereum validator builds a block, it runs each user's transaction on the spot before picking the next one. Because it runs the code immediately, it sees the exact Gas Used right away and knows exactly how much space is left in the block for the next person.
Monad (Booking Cargo on a Flight): To process thousands of transactions per second, Monad uses asynchronous execution: validators pack transactions into a block and lock in the order before running the smart contract code. Because the network hasn't run your code yet when packing the block, it doesn't know what your actual Gas Used will be--it only sees the Gas Limit you asked to reserve!

If Monad let users reserve massive amounts of block space using a huge Gas Limit and then only charged them for a tiny Gas Usedafterward, someone could reserve an entire block, crowd out everyone else on the network, and pay almost nothing. Just like reserving 10 seats on a bus or cargo flight where other passengers have to be turned away at the gate, on Monad you pay for the exact capacity you reserve upfront (Gas Limit).

Case Study Two: Inspecting a Transaction on Ethereum Sepolia Testnet

To see how standard Ethereum fee accounting differs, I went to the Ethereum Sepolia Testnet block explorer and pulled up a random transaction hash to inspect its receipt. In this transaction, the sender called the close() function on a smart contract.

Here are the transaction details:

Field	Value
Network	Ethereum Sepolia Testnet
Function Called	`close()`
Transaction Status	Success
Transaction Value	0 ETH
Gas Limit	156,059
Gas Used	152,492
Gas Usage	97.71%
Effective Gas Price (as reported)	0.000153611 Gwei
Transaction Fee	0.000000023424448612 ETH

Gas Limit vs. Gas Used (And What Happens to Unused Gas)

Just like the Monad transaction, this transaction sent 0 ETH in value while paying a fee to execute smart contract logic. However, look at the difference between the limit and the actual consumption.

Gas limit: 156,059
Gas used: 152,49

156,059 - 152,492 = 3,567 unused gas

Percentage Consumed = (152,492 ÷ 156,059) × 100 ≈ 97.71%

Here, the transaction consumed 97.71% of its limit and left 3,567 gas (2.29%) untouched.

What happens to that 3,567 unused gas on Ethereum?

When a transaction begins on Ethereum, the protocol temporarily locks enough ETH from the sender's balance to cover the entire 156,059 Gas Limit (just like a fuel pump pre-authorizing your card before you pump). As the code executes, the meter ticks up to 152,492. The moment execution finishes, the leftover 3,567 gas is immediately refunded back to the sender's wallet inside the exact same transaction, and that unused capacity is freed up for other transactions in the block.

How the Sepolia Transaction Fee Was Calculated

Because Ethereum refunds unused gas, the final fee is calculated strictly on Gas used:

Transaction fee = Gas used x Effective gas price

Multiplying the 152,492 gas actually consumed by the 0.000153611 Gwei effective gas price:

152,492 x 0.000153611 Gwei = 23.424448612 Gwei

Since 1 ETH = 10⁹ Gwei:

Fee = 23.424448612 ÷ 10⁹ = 0.000000023424448612 ETH

Notice that the unused 3,567 gas was never charged to the sender.

How Do You Know What Gas Limit to Set?

Looking at numbers like 49,785 on Monad and 156,059 on Sepolia, a natural question comes up: How does anyone know how much gas a contract will need before sending the transaction?

You don't have to calculate opcodes manually. In practice, gas limits are estimated automatically:

Wallet & RPC Simulation (eth_estimateGas): Before you click "Confirm" in your wallet, the wallet silently calls a method on an RPC node called eth_estimateGas. The node runs a free practice simulation (dry run) of your transaction against the current state of the blockchain in its local memory, counts the exact gas used, and reports that number back. Your wallet then adds a small safety buffer (often 10% to 20%) in case the blockchain state changes slightly before your transaction lands in a block.
Developer Tooling (Foundry): When writing smart contracts in Foundry, running forge test --gas-report or cast estimate simulates your function calls and prints out the exact gas numbers before you ever deploy to a live network.

Practical takeaway: Because Monad charges you for your declared Gas Limit, you should rely on eth_estimateGas with a modest buffer rather than manually typing in an artificially huge gas limit!

Understanding Gas Price and Gwei

Now that we've covered Gas Limit and Gas Used, let's look at Gas Price and Gwei

While gas measures the computational effort (liters of fuel), gas price is the monetary cost per single unit of gas (price per liter). Because a single unit of gas costs a tiny fraction of 1 ETH or 1 MON, we express gas prices in Gwei (short for Giga-wei) so we don't have to read strings of nine zeros:

1 ETH (or MON) = 10⁹ Gwei = 1,000,000,000 Gwei

1 Gwei = 0.000000001 ETH

When someone says "Gas price is 20 Gwei," they don't mean the whole transaction costs 20 Gwei. They mean each single unit of gas costs 20 billionths of an ETH.

Suppose a transaction consumes 50,000 gas:

At 10 Gwei per gas: 50,000 x 10 Gwei = 500,000 Gwei (0.0005 ETH).
At 20 Gwei per gas: 50,000 x 20 Gwei = 1,000,000 Gwei (0.001 ETH).

Notice that the computational work (50,000 gas) stayed completely identical--the fee doubled purely because network demand pushed the price per unit of gas twice as high.

Decoding EIP-1559: Base Fee, Priority Fee, and Max Fee

Both the Monad and Sepolia receipts identify the transaction type as EIP-1559 (Type 2). Under EIP-1559, the gas price is broken down into specific components. Let's look at the fee breakdown from the Sepolia receipt:

Fee Field	Value
Network	Ethereum Sepolia Testnet
Base Fee	0.000000015 Gwei
Max Priority Fee	0.000153596 Gwei
Max Fee	0.000153614 Gwei
Effective Gas Price	0.000153611 Gwei

Here is how these four numbers fit together:

Base fee (0.000000015 Gwei): The mandatory minimum rate per unit of gas for that block, determined automatically by the network based on how full previous blocks were. On Ethereum, the base fee is burned (destroyed) rather than paid to the block proposer.
Max priority fee (0.000153596 Gwei): The maximum tip per unit of gas the sender offers directly to the block proposer (validator) to incentivize them to include the transaction.
Max fee (0.000153614 Gwei): The absolute ceiling per unit of gas the sender is willing to pay in total (Base fee + Priority fee) in case the base fee jumps while the transaction is waiting.
Effective gas price (0.000153611 Gwei): The actual rate per unit of gas charged when the block was produced:

Effective gas price = Base fee + Effective priority fee

0.000000015 Gwei + 0.000153596 Gwei = 0.000153611 Gwei

Because 0.000153611 Gwei was safely below the sender's Max fee cap of 0.000153614 Gwei, the transaction paid the exact sum of the base fee and priority tip.

Why Do Transactions Need a Gas Limit? (And Why Gas Costs Change)

Preventing Runaway Code

Why does every blockchain transaction require a Gas Limit in the first place? Consider a contract function with a massive loop:

function expensiveOperation() external {
    uint256 total;

    for (uint256 i = 0; i < 1_000_000; i++) {
        total += i;
    }
}

If a transaction could execute without an upper bound--or accidentally hit an infinite loop--every node on the network would get stuck executing that loop forever, halting the blockchain.

The Gas Limit acts as a circuit breaker. If a transaction burns through all of its allotted gas before finishing, it stops with an Out of Gas error. When that happens, all state changes are reverted as if the transaction never happened, but the sender still pays for the gas consumed because the network already spent real computational work running the code up to that point.

Keep in mind: having plenty of gas does not guarantee a transaction will succeed. If a contract fails an internal require check or permission rule, the transaction will still revert even with gas left over.

Why Two Calls to the Same Function Can Use Different Gas

It is also easy to assume that calling the same function with the same inputs will always consume the exact same amount of gas. In practice, gas usage depends on the exact state of the contract at the moment of execution.

For example, in our Counter contract, the very first call to increment() updates count from 0 to 1. Allocating a brand-new storage slot from zero to a non-zero number costs 20,000 gas. The next call updates count from 1 to 2--and overwriting an already non-zero storage slot costs 2,900 gas. Even though both users called increment(), the first call performed heavier database work under the network's rules.

Comparing the Two Receipts: Are Fees on Monad Expensive?

Let's put our Monad Testnet interaction and the Sepolia Testnet receipt side by side

Concept	Monad Testnet: `increment()`	Sepolia Testnet: `close()`
Gas Limit	49,785	156,059
Gas Used	49,785	152,492
Gas Usage	100%	97.71%
Effective Gas Price (as reported)	102.82 Gwei	0.000153611 Gwei
Transaction Fee	0.0051188937 MON	0.000000023424448612 ETH
Fee Calculation	Gas Used x Gas Price	Gas Used x Effective Gas Price

When you look at this table, you might notice that 102.82 Gwei (0.0051 MON) looks numerically much larger than 0.000153611 Gwei (0.0000000234 ETH). Does that mean gas fees on Monad are expensive?

Not at all. In real-world dollar terms, Monad is designed so transactions cost a fraction of a cent. Those raw numbers cannot be compared directly for two reasons:

Different Native Tokens (MON-Gwei vs. ETH-Gwei): 1 Gwei on Ethereum is one-billionth of 1 ETH (an asset priced in thousands of dollars), whereas 1 Gwei on Monad is one-billionth of 1 MON. Comparing 0.005 MON to 0.00000002 ETH is like comparing 50 Naira (or 5 Japanese Yen) to 0.03 US Dollars--a bigger number in one currency doesn't mean a higher cost!
Monad's 100 Gwei Minimum Base Fee Floor: To prevent spam when blocks aren't full, Monad enforces a minimum base fee of 100 MON-gwei (which is why our transaction was 102.82 Gwei: 100 Gwei base fee + 2.82 Gwei priority tip). Sepolia Testnet has no 100 Gwei floor, so its testnet base fee had drifted down to nearly zero (0.000000015 Gwei).

Common Misunderstandings About Gas (Quick Checklist)

Gas and cryptocurrency are the same thing. They are not. Gas is a measurement of computational work; ETH and MON are the native assets used to pay for that work.
The gas limit is the exact amount of gas a transaction will use. Not necessarily. The gas limit is the maximum allowance; actual execution often consumes less.
A transaction with 0 value is free. Incorrect. Both of our transactions had a value of 0, and both required fees to pay for smart contract execution.
A higher gas limit always means a higher fee. It depends on the network's architecture! On Ethereum, you are only billed for Gas Used, and unused gas is refunded. On Monad, because blocks are packed asynchronously before execution, you are billed for the entire Gas Limit you reserve.
Enough gas guarantees a transaction will succeed. Incorrect. Even with plenty of gas, a transaction will revert if it hits a failed contract condition or permission check.

How to Explain Gas to Someone Else

If someone asks you, "What is gas on the blockchain, and how do fees work?", here is how you can break it down cleanly

Gas is the unit that measures how much computational work a transaction requires--just like liters of fuel needed for a delivery truck to complete a trip.

Every transaction sets a Gas Limit (calculated automatically by your wallet simulating the transaction), which acts as a maximum fuel cap so a bad loop can't run forever. As the transaction runs, it tallies up the Gas Used based on the exact instructions executed.

To find the Transaction Fee, you multiply the gas quantity by the Gas Price (measured in Gwei). On Ethereum, you only pay for the fuel your code actually burned (Gas Used), and any unused gas is refunded immediately. On high-speed asynchronous networks like Monad, where block space is reserved before running the code, you pay for the entire fuel limit you reserved upfront (Gas Limit).

Once you separate the unit of work, the maximum allowance, the actual consumption, and the price per unit, any transaction receipt on any EVM block explorer becomes intuitive to read.

Let's Figure Out the Rest Together

Writing this guide started with a simple realization: it is completely normal to use blockchains, deploy contracts, and still feel a bit fuzzy on what every single line of a transaction receipt is actually telling you. Moving from memorizing definitions to tracing the exact numbers is how the mental model finally clicks.

Now I'd love to hear from you: What part of Gas still feels unclear, confusing, or tricky to explain?

Is there a field on a block explorer receipt that you've always wondered about?
Have you ever run into an unexpected Out of Gas error or a strange gas estimation spike while testing a contract?
Or do you have a favorite real-world analogy of your own for explaining gas, Gwei, or EIP-1559 to someone new?

Drop your questions, edge cases, or thoughts in the comments below--no question is too basic or too far down the rabbit hole. Let's unpack them together.

BinnaDevLab
Reasoning Precedes Coding.

What the DAO Hack, Parity Freeze and Ronin Exploit Teach Us About Immutability

Obinna Duru — Mon, 12 Oct 2026 08:09:01 +0000

In 2016, an attacker discovered a bug in a smart contract called the DAO.

He didn't need to compromise Ethereum. He didn't need a zero-day exploit. He found one bad assumption in the withdrawal logic, wrote a contract that exploited it recursively, and drained $60 million. Every node on the Ethereum network confirmed every transaction. The blockchain did its job perfectly.

That's the thing about immutable code. It can't lie. But it also means it can't be fixed.

I've been sitting with this idea since I hosted Session 3 of BinnaDevLab Cohort 1. I invited Uchenna Ofoma, a software engineer of 3+ years currently focused on the distributed systems that underpin blockchain technology, to walk us through the full engineering reality of deploying code you can never take back. What followed was one of the most honest breakdowns of Web3 security I've heard.

If you'd rather watch than read, here's the full 42-minute session:

What "Deploying" Actually Means

I opened the session by framing the core question: what does it actually mean that a smart contract is immutable?

Most developers have an intuition for deployment -- you push code, it runs on a server, the server can be updated or rolled back. Uchenna immediately challenged that mental model.

When you deploy a smart contract, your code gets compiled to EVM bytecode -- an intermediate representation designed specifically to run on the Ethereum Virtual Machine. From that moment, your code gets a permanent address. Every node on the network holds a copy and can execute it. Nobody owns the server. There is no centralized server.

As Uchenna put it: "Once you deploy your smart contract, just take it that it's online forever or until the blockchain inevitably goes down someday, somehow."

The reason for this is deterministic execution. The EVM guarantees that given the same inputs, every node produces the same output. This is what makes decentralization possible: no one node needs to be trusted, because they all agree on the math. But it also means your bug is their bug permanently.

Two Kinds of Trust

Before Uchenna walked us through what goes wrong, he established something I thought was fundamental and it connects directly back to what we covered in Session 1.

"If the owner can go to edit the rules, you're back to trusting a company, which is what we're trying to avoid."

The whole promise of a smart contract is that you're replacing trust in a person with trust in code. Anyone can audit it. Anyone can verify it. It runs without asking permission. But the moment you give an admin the ability to change the code, you've reintroduced a human and with it, all of human failure.

That's the foundation:

"A contract you can edit is not an agreement -- it's a promise."

When Uchenna said that, I wrote it down immediately. It cuts straight to why any of this matters.

When Forever Goes Wrong

This is the section of the session I wasn't fully prepared for. I knew Uchenna was going to cover the major hacks. I didn't expect the specific engineering detail he brought to each one.

The DAO $60 million Hack

The DAO was a decentralised fund on Ethereum. Members could pool ETH and vote on how to allocate it. A smart contract managed all the funds.

There was a bug, a re-entrancy bug. Uchenna explained it in a way that made it immediately understandable:

The contract let you withdraw your balance. But before it updated your balance, it made an external call to send you the ETH. An attacker wrote a contract that, the moment it received ETH from the withdrawal, immediately called the withdrawal function again before the balance had been marked as zero. Then again. And again.

He kept entering the vault before it could record that he'd left.

By the end, he had drained approximately $60 million. The code didn't fail. No exception was thrown. The EVM executed every call exactly as instructed.

The fix for this pattern is called Checks-Effects-Interactions: update all your state variables before you make any external calls. Mark the balance as zero first. Then send the money. If someone tries to re-enter, they find an empty account.

The aftermath is one of the most significant moments in blockchain history. The Ethereum community forked the chain -- creating a copy up to just before the hack -- so that affected users could get their money back. The old chain, where the attacker kept his funds, became what we now know as Ethereum Classic. The blockchain literally split in two over one bug.

The Parity Wallet Freeze -- $280 million

In 2017, Parity Technologies built a popular multi-signature wallet. Multiple signatures were required to move funds, no one person could act alone.

The problem was architectural. Their wallets shared a single library contract. That library had an unguarded initialization function, no access control, no guard on who could call it.

A user exploring the code called it. Then, exploring further, called the function to delete the library.

$280 million was locked. Not stolen. Just permanently inaccessible, because the code that would authorise withdrawals no longer existed.

The fix is access control: every state-changing function needs to verify who is calling it before allowing the action to proceed.

The Ronin Sidechain Exploit -- $625 million

Ronin was the sidechain powering Axie Infinity. To validate transactions, it used nine validator keys. A majority, five of nine was required to approve any action.

Attackers compromised five of them.

Uchenna's analogy during the session stuck with me: "Half of nine is 4.5. They've compromised five. Five is more than 4.5."

With majority control, the attackers could authorize anything. $625 million left. The code worked exactly as designed. It was just the wrong people holding the keys.

How Engineers Live With It

After walking through what failed, Uchenna shifted to what engineers do in response. The honest answer is that there are no perfect solutions, only trade-offs.

Proxy Contracts: You can deploy a "proxy" that users interact with, which delegates logic to an implementation contract behind the scenes. When you need to patch a bug, you deploy a new implementation and point the proxy at it. The address never changes. The logic does.
Time Locks: Any upgrade or large fund movement gets queued with a delay like 72 hours. This gives the community time to notice if something suspicious is being pushed.
Multi-sig wallets: No single person can push the button. A 3-of-5 multi-sig requires three separate private keys to sign any transaction.
Third-party audits and bug bounties: Independent firms review your code. Or you open a bounty for anyone to report a vulnerability, get paid. The goal is to maximize the number of friendly eyes before deployment, because after deployment, every eye is potentially hostile.

Every Escape Hatch Is Also an Attack Hatch

This was the moment of the session that landed hardest.

Every mechanism you build to survive a bug is also a mechanism an attacker can use against you.

Proxy contracts? An attacker who controls the admin key can push a malicious implementation.

Time locks? The attacker now has 72 hours to prepare not just a few seconds.

Uchenna's framing:

"An immutable bug is honest. An upgradeable protocol is a promise with a delay."

An immutable contract is what it is. Its failure mode is fixed and visible. An upgradeable contract introduces ongoing risk: the humans holding the upgrade keys, forever. If those humans are ever compromised or ever act against users' interests, the upgrade path becomes the exploit.

The engineer's job, as Uchenna put it, is to decide which failure they can live with.

DYOR Is Not Just a Meme

I closed the session with something I feel strongly about, and I want to say it directly here too.

DYOR (Do Your Own Research), gets thrown around in crypto circles as a joke or a liability disclaimer. But after what Uchenna walked us through, it's the only honest answer to the immutability problem.

If you're building: audit your code, run open-source tools against it, get third-party reviews, and be honest about what your protocol assumes. Know what your upgrade path actually exposes.

If you're using: don't trust a protocol because the team told you to. Find the audit report. Look at who holds the keys. Understand whether the thing you're interacting with is truly immutable or whether there's an admin somewhere with a button.

The code can't lie. But you need to be able to read it.

We're running Cohort 1 of BinnaDevLab: a structured developer program built on reasoning from first principles. Session 3 was the theory. Session 4 is the practical: actually writing smart contracts and experiencing immutability firsthand.

Missed Session 1 on trust and decentralization? Watch it here.

Follow along on YouTube or join the community at binnadev.com

Blockchain Isn't About Crypto. It's About a Trust Problem You Didn't Know You Had.

Obinna Duru — Wed, 07 Oct 2026 10:28:13 +0000

Before we started the first session of BinnaDevLab Cohorts, I knew one thing with certainty:

If we opened with the word "blockchain," we'd lose half of the room.

Not because the topic is hard. Because the word carries baggage. Crypto speculation. NFT mania. Headlines about scams and volatility. By the time most developers hear "blockchain," they've already formed an opinion and it's usually dismissive.

So we didn't start there.

We started with a question.

"Think of an app you used this morning. Name it."

That was the warm-up exercise Uchenna Ofoma, our facilitator for Session 1 put to the cohort.

The answers came quickly.

Opay. WhatsApp. Gmail. Facebook. Sporty.

Uchenna nodded at each one. Then he asked the follow-up question. The one that changed everything:

"Who were you actually trusting?"

The room went quiet.

Not the app. Not the company. When you send ₦5,000 on Opay, you're trusting:

Opay's servers to record the transaction accurately
The commercial bank Opay connects to
NIBSS to clear the interbank transfer
The KYC provider that verified both account holders
The CBN regulatory framework sitting beneath all of it

You weren't trusting one party. You were trusting a chain and you had zero visibility into any link of it.

That's not a crypto problem. That's not a web3 problem. That's a software engineering problem that exists in every application you've ever built or used.

And that is the real reason blockchain was invented.

Why We Built BinnaDevLab Around This

When I started BinnaDevLab Cohorts, the goal was simple but specific: train developers to reason at a global level not just to write code, but to understand why systems are designed the way they are.

The industry is full of bootcamps that teach you to ship fast. We wanted to build something different. A program built on the principle that reasoning comes before coding. That understanding the problem deeply is the actual skill, the code is just the output.

Blockchain was the perfect first topic. Not because it's trendy. Because it sits at the intersection of distributed systems, game theory, cryptography, and trust and most introductions to it skip all of that in favour of price charts.

We wanted to go the other way.

What Actually Happens When Trust Breaks

🎬 Prefer to watch? The full 64-minute session is on YouTube
Blockchain Fundamentals Explained | BinnaDevLab Cohort 1, Session 1

Uchenna spent the core of Session 1 on a deceptively simple question: where does the trust network fail?

The answer: single points of failure.

Every link in that chain we described: Opay, the bank, NIBSS, the KYC provider is a centralised entity. That means:

One server goes down -> transactions fail
One database is compromised -> your data is leaked
One regulatory decision -> your account is frozen without warning
One bad actor inside the organisation -> the records are altered

You have no way to verify what's happening. You're trusting the institution to be honest, competent, and well-intentioned. Usually they are. But the system requires you to trust them, you have no alternative.

Blockchain's argument is not that institutions are corrupt. It's that you shouldn't have to assume they're honest. The system should be designed so that anyone can verify the truth not just the people running the servers.

In practice, that means:

Instead of rules locked on a private server -> rules deployed as code, in public
Instead of promises -> anyone can read the code and check exactly what it does
Instead of one keeper -> everyone keeps a copy, and no single party can rewrite history

That's not magic. That's engineering. And it comes with real costs.

The Honest Trade-offs (Most Courses Skip This Part)

One of the things I'm proudest of in how Uchenna ran Session 1 is that he didn't sell blockchain. He explained it including the parts that hurt.

Distributed verification is slower than a centralised server. Always. If you need instant transaction finality, a blockchain is the wrong tool.

It's more expensive to run. Every node in the network has to process every transaction. That cost is real and it compounds at scale.

Finality works differently. On your bank app, if you send money to the wrong person, you call customer service. On a public blockchain, the transaction is final. There is no customer service. The code runs.

And perhaps the sharpest point: blockchain doesn't remove trust. It relocates it. You stop trusting institutions and start trusting code, mathematics, and the incentive structures of a decentralised network. That's a different kind of trust, more auditable, more transparent, but trust nonetheless.

Understanding those trade-offs is what separates engineers who can reason about distributed systems from developers who just know how to call a Web3 library.

Watch the Full Session

Everything I've described above is the skeleton of a 64-minute live session with audience interaction, Q&A, and a cohort working through these ideas in real time.

Uchenna also covered:

A brief history of blockchain (Bitcoin 2008 -> Ethereum 2015 -> today)
Public vs. private blockchains and why each exists
What Ethereum and the EVM actually are
What people are building on Ethereum right now
Consensus mechanisms: Proof-of-Work, Proof-of-Stake, Proof-of-History
A live Q&A: does blockchain make systems trustless, or does it just shift the trust?

If this article gave you the argument, the video gives you the full picture including the moments where the cohort pushed back and Uchenna had to defend his reasoning in real time.

That's the kind of session we wanted to build. Not a lecture. A thinking session.

Watch here 👉 Blockchain Fundamentals Explained | BinnaDevLab Cohort 1, Session 1

What's Next

Session 2 is hands-on. Obinna takes the cohort from theory into code writing and deploying a smart contract in Solidity, live.

If Session 1 answers why blockchain exists, Session 2 answers how you build on it.

Follow BinnaDevLab to catch it when it drops.

About BinnaDevLab

BinnaDevLab is a developer training community built around one idea: reason before you code.

We run structured cohorts for developers who want to build with depth not just ship fast.

🌐 binnadev.com

ERC20 Edge Cases Every Smart Contract Engineer Should Know

Obinna Duru — Wed, 07 Oct 2026 09:49:00 +0000

Your protocol launches. Everything passes the test suite with 100% coverage. Your audits are clean.

Then, an unexpected token enters your liquidity pool. The accounting drifts by a fraction of a percent. Within hours, the discrepancy compounds. Users attempt to withdraw, and the transactions revert. The vault is permanently bricked, and funds are stuck.

What went wrong?

Most ERC20 exploits are not actually bugs in the protocol's core logic. They happen because protocol engineers assume every token behaves exactly like a vanilla OpenZeppelin implementation.

The ERC20 standard is an interface, not a guarantee. It defines function signatures (transfer, approve, balanceOf), but it dictates absolutely nothing about the internal execution logic behind those signatures.

If your protocol integrates arbitrary tokens, your threat model immediately includes the behavior of those tokens. A single flawed assumption about how a token transfers, reverts, or accounts for balances can lead to systemic insolvency.

Let's look under the hood of the most common ERC20 edge cases that break production systems, and how to engineer defensive architectures to mitigate them.

The Four Assumptions That Break Integrations

Before we look at specific edge cases, it helps to build a mental model of why these failures happen. Almost every ERC20 integration bug stems from one of four flawed assumptions:

Amount Assumptions: Believing the amount you request to transfer is the exact amount that will arrive.
Execution Assumptions: Assuming token transfers are passive state updates, rather than active execution environments.
Permission Assumptions: Believing that having a sufficient balance and allowance guarantees a transfer will succeed.
Accounting Assumptions: Hardcoding precision logic or assuming token behavior is immutable.

Let's break down how these assumptions fail in production.

Edge Case #1: Fee-on-Transfer & Rebasing Tokens

The assumption
If I call token.transferFrom(alice, vault, 100), the vault's balance increases by exactly 100.

What actually happens
Tokens can deduct a tax on transfer (e.g., a 5% protocol fee) or continuously alter user balances algorithmically (rebasing).

Example failure
A user deposits 100 fee-on-transfer tokens. The token takes a 5% fee.

User calls deposit(100)
👇
Token executes transfer, deducts 5% tax
👇
Vault receives 95 tokens

❌ Vault internally mints 100 shares based on 'amount' parameter
✅ Vault should mint 95 shares based on actual received funds

Because the vault blindly minted 100 shares, the user can immediately withdraw 100 tokens, successfully stealing 5 tokens from previous depositors. The accounting drifts, and the last users to withdraw will be left with nothing.

Mitigation
Never trust the amount parameter for internal accounting. Always measure the actual balance delta before and after the transfer.

uint256 balanceBefore = token.balanceOf(address(this));
token.safeTransferFrom(msg.sender, address(this), amount);
uint256 balanceReceived = token.balanceOf(address(this)) - balanceBefore;

// Use balanceReceived for all subsequent logic, never 'amount'
_mintShares(msg.sender, balanceReceived);

Takeaway: Balance-delta accounting fixes this assumption. Unfortunately, the next edge case breaks protocols even when the balances match perfectly.

Edge Case #2: Tokens with Callbacks (ERC-777 & Transfer Hooks)

The assumption
Calling transfer only updates storage balances and returns execution flow directly back to my contract.

What actually happens
Standards like ERC-777, or custom tokens with transfer hooks, actively hand execution control back to the sender or receiver via external calls during the transfer process.

Example failure
Your protocol updates the user's internal debt balance after pushing tokens to them.

User calls withdraw()
👇
Protocol calls token.transfer(user)
👇
Token calls back to User's smart contract
👇
User's contract calls withdraw() AGAIN (before protocol debt is updated)

This is a classic reentrancy attack, facilitated entirely by the token's internal hook.

Why This Surprises Engineers: We naturally view tokens as passive data ledgers. Callbacks turn tokens into active, hostile execution environments.

Mitigation
Follow the Checks-Effects-Interactions (CEI) pattern religiously. Update all internal state before interacting with external tokens. Additionally, apply OpenZeppelin's ReentrancyGuard (nonReentrant modifier) to any function interacting with external tokens.

Takeaway: Reentrancy guards handle unexpected execution paths. But what happens when a token quietly fails without telling you?

Edge Case #3: Returning false vs. Reverting

The assumption
If a token transfer fails, the transaction will revert.

What actually happens
Some older tokens (like ZRX) do not revert on failure. Instead, they gracefully return a false boolean.

Example failure
Your protocol calls token.transfer(user, amount)and doesn't check the return value. The transfer fails (returns false), but your code continues executing. The protocol marks the user's debt as paid, even though no tokens actually moved.

Mitigation
Never use bare transfer or transferFrom calls. Wrap them in logic that asserts the boolean return value is true.

OpenZeppelin / best practice
Always use OpenZeppelin's SafeERC20 library (safeTransfer, safeTransferFrom). It normalizes behavior by forcing a silent false failure to revert.

Takeaway: SafeERC20 forces silent failures to revert. But occasionally, you actually want certain transfers to bypass reverts.

Edge Case #4: Zero Address & Zero Amount Reverts

The assumption
Transferring an amount of 0 is a harmless No-Op (no operation) that costs a little gas but executes successfully.

What actually happens
Different token implementations handle zeros differently. Some explicitly revert if the transferred amount is 0, or if the target is the zero address.

Imagine this scenario:
Your protocol distributes daily yields in a batch loop to 100 users. One user earned 0 yield today. The loop attempts to transfer(user, 0). The token reverts, crashing the entire transaction and preventing the other 99 users from receiving their yields.

Mitigation
Standardize behavior by wrapping transfers in a simple defensive check to bypass zero-amount logic.

if (amount > 0) {
    token.safeTransfer(user, amount);
}

Takeaway: Standardizing behavior protects your loops. But what if the token completely breaks the standard interface?

Edge Case #5: Missing Return Values (The USDT Problem)

The assumption
All ERC20 tokens return a boolean, as dictated by the standard interface.

Production Reality: Tether (USDT) on Ethereum Mainnet is non-standard. Its transfer, transferFrom, and approve functions do not return a boolean; they return void.

Example failure
If your contract compiles against the standard IERC20 interface, the EVM expects boolean return data to decode.

Standard: function transfer(...) returns (bool)
USDT:     function transfer(...) [returns void]
EVM:      "Wait, where is the boolean to decode? Revert."

Your protocol completely fails to integrate with the largest stablecoin on the market.

Mitigation
OpenZeppelin's SafeERC20 handles this under the hood. By using safeTransfer, you safely abstract away the missing return value issue at the assembly level.

Takeaway: SafeERC20 handles legacy interfaces. But interface compatibility won't save you from centralized control.

Edge Case #6: Blacklisted Addresses

The assumption
If an address has a sufficient balance and allowance, a transfer will always succeed.

What actually happens
Fiat-backed stablecoins like USDC and USDT maintain centralized blacklists. If an address is blacklisted, all transfers involving that address will revert.

Example failure
Your protocol liquidates undercollateralized debt. To close a position, it must send leftover USDC collateral to the user. The user gets blacklisted by Circle. The liquidation transaction reverts when attempting to send the leftover funds, preventing the protocol from clearing bad debt. The systemic risk cascades, threatening protocol solvency.

Design Rule: Pull-over-Push
Decouple protocol logic from token transfers. Instead of pushing funds to a user during a critical state change, record their balance internally and force them to pull (claim) it in a separate transaction.

Takeaway: Decoupling logic prevents centralized blacklists from freezing your protocol. Speaking of centralized quirks, let's look at approvals.

Edge Case #7: Non-Zero Approval Restrictions

The assumption
You can update an allowance from any number to any other number using approve(spender, newAmount).

What actually happens
To prevent approval front-running (where an attacker exploits an old allowance while a new one is pending), tokens like USDT require that allowances be reset to 0 before being updated to a new non-zero value.

Example failure
A router contract tries to update its USDT approval to a DEX from 50 to 100. It calls approve(dex, 100). Because the current allowance is 50 (non-zero), USDT reverts the transaction.

Mitigation
You must approve 0 before approving the target amount. In OpenZeppelin v5+, safeApprove was removed. Use forceApprove(), which natively handles the 0 reset under the hood.

Takeaway: Approval races are tricky, but at least the token is always the token... right?

Edge Case #8: Multiple Addresses for the Same Token

Mental Model: Think of an ERC20 token as a ledger. Usually, there is one door to access that ledger. But sometimes, developers build multiple doors (proxies, wrappers, aliases) that lead to the exact same ledger.

What actually happens
Some tokens (like older TrueUSD implementations) use multiple entry point addresses that point to the same underlying state.

Example failure
A lending protocol relies on the token's contract address as a unique identifier for price feeds. An attacker uses a wrapper contract that proxies to the same underlying token. The protocol reads the proxy as an unverified token, misprices the collateral, and allows the attacker to borrow against manipulated values.

Mitigation
Identify tokens strictly by exact, whitelisted addresses. Never rely blindly on msg.sender to dynamically determine asset identity.

Takeaway: Identity is fluid. And worse, token logic is mutable.

Edge Case #9: Upgradeable Tokens

The assumption
The token behavior I test today will be the token behavior in production tomorrow.

What actually happens
Tokens like USDC are upgradeable behind a proxy. The controlling entity can push an upgrade at any time, adding transfer fees, callbacks, or entirely new operational restrictions.

Example failure
You build a protocol assuming USDC has no fee-on-transfer. Circle upgrades USDC to enforce a 1 basis point transaction fee. Your static accounting breaks, and protocol funds become permanently locked because the math no longer balances.

Mitigation
Code defensively. Use balance-delta accounting (Edge Case #1) even if the token currently doesn't require it. Build pause functionality into your own protocol so you can halt operations if an upgrade breaks your integration.

Takeaway: You can't control token upgrades, but you can control how you calculate value. Which brings us to spot balances.

Edge Case #10: Flash-Mintable Tokens

The assumption
Massive token balances represent real, scarce capital.

What actually happens
Some tokens, like DAI, natively support flash-minting. A user can instantly mint millions of tokens in a single transaction, provided they are burned (with a fee) by the end of execution.

Example failure
Your protocol calculates governance voting power based on spot balances within a liquidity pool. An attacker flash-mints 100 million DAI, executes a massive governance manipulation, and repays the DAI in the same block.

Mitigation
Never rely on spot balances for price discovery or voting power. Use Time-Weighted Average Price (TWAP) oracles and historical checkpoints.

Takeaway: Spot balances lie. And sometimes, tokens lie about how much they transferred, too.

Edge Case #11: Transferring Less Than Requested

The assumption
If I request to transfer type(uint256).max, the token will either transfer that exact enormous amount or revert.

What actually happens
Some obscure tokens treat an amount parameter of type(uint256).max as a custom flag meaning "transfer all of the user's available balance."

Example failure
A protocol requests a uint256.max sweep. The token successfully transfers the user's actual balance of 50 tokens. The protocol incorrectly records that type(uint256).max tokens were received, creating massive artificial inflation.

Mitigation
Once again, balance-delta accounting saves the day. Never assume the requested amount is the executed amount.

Edge Case #12: High-Decimal Tokens

The assumption
Tokens either have 18 decimals (like ETH) or 6 decimals (like USDC).

What actually happens
Tokens like YAMv2 use 24 decimals.

Example failure
Your protocol multiplies a token balance by a high-precision constant before dividing it. Because the token already has 24 decimals, the multiplication exceeds type(uint256).max and triggers an unexpected math overflow, bricking the transaction.

Mitigation
Always dynamically read the decimals() function and normalize balances to a standard precision internally before performing complex math.

Bonus Edge Cases

Edge Case #13. Pausable Tokens:
Tokens can be globally paused by their admins. Ensure your system degrades gracefully and uses Pull-over-Push accounting so a globally paused token doesn't brick your entire transaction loop.

Edge Case #14. Large Approval/Transfer Reverts:
Tokens like UNI and COMP use uint96 for their internal accounting limits. Attempting to approve or transfer uint256.max will unexpectedly revert. Always approve exact required amounts.

Defensive ERC20 Integration Checklist

Before deploying any contract that touches external ERC20 tokens, verify your architecture against these rules:

Are you using SafeERC20? Never use bare .transfer() or .transferFrom().
Are you measuring balance deltas? Never assume amount sent == amount received.
Are you safe from reentrancy? Assume every token transfer is an external callback.
Are you using Pull-over-Push? Ensure a failing transfer only affects the specific user, not the broader system loop.
Have you normalized decimals? Do not assume 6 or 18 decimals.
Do you rely on spot balances? Ensure oracles and voting mechanisms cannot be manipulated via flash-mints.

Closing Thoughts

Smart contract engineering is deeply unforgiving because you are not just building software; you are building immutable financial infrastructure.

When you integrate an external token, you do not just integrate an asset. You inherit its execution models, its upgrade paths, its governance assumptions, and its operational constraints. If the token's logic changes, or if it behaves in a way you didn't model for, your protocol pays the price.

Treat every external token as fundamentally hostile. Rely on pure math, stateful invariants, and defensive accounting.

Reliable systems emerge from reducing assumptions. Let's build something we can trust.

What edge cases have caused problems in your own deployments? Let's chat about it in the comments below. Follow for more deep dives into smart contract architecture and onchain security.

The Internet Hasn't Changed

Obinna Duru — Mon, 07 Sep 2026 12:11:38 +0000

Before we argue about the future of the web, we need to understand what it has always been: one continuous system of innovation built on the exact same foundation.

Let's start with the Web3 ecosystem.

When people talk about Web3, the conversation usually gets tangled up in tokens, hype, and technical buzzwords. But at BinnaDevLab, when we talk about the Web3 ecosystem, we are not talking about a completely different technology. We are referring to the internet as a whole, viewed from Version 3.

Because the truth is, the internet hasn't fundamentally changed.

The internet has always been a means of connection. The core idea is simply to bring people together, share resources, and bridge communication. If you Google the word "Internet," you'll get a definition something like this: a global system of connected computer networks that people use to share information and communicate worldwide.

Over the years, we have experienced completely different ways of doing this. We went from writing letters and painting on walls, to static web pages, social media apps, and streaming reels. It feels like a different world, but it is just a system of innovation built on the exact same block.

The Water Analogy

Think about drinking water for a second.

In ancient times, people used their hands, clay pots, or carved artifacts to draw water. Today? We use modern dispensers, insulated smart cups, and bottled cans. The method changed entirely, but the fundamental action remained exactly the same: we are still drinking water.

The point of innovation is not to change the fundamental purpose. It is to improve the vessel that delivers it.

Bring this to the internet. When you strip away the buzzwords, the internet is simply our vessel for communication. The changes that happen over time are just iterations. We attach numbers to them, but if you look closely, they all mean the same thing.

Season 1: The "Read-Only" Web

When you see the word "Web1," what is the first thing that comes to your mind?

We all know the "web" is the internet. But when we attach a "1" to it, it triggers curiosity. Why call it 1?

It's just like a television series. You have Season 1, Season 2, and Season 3. The numbers are simply there to show progression. Innovation is a progression; it has different iterations, and we need to keep track of it. Web1 just means the first version of the show.

So, what did Season 1 of the internet look like? Take a pause and think about it for a minute.

Web1 was the "read-only" web.

Companies published, and you consumed. You could visit a website and read what was there, but you couldn't easily comment, post, or interact. The information was mostly static text and typed documents.

But at the time, it solved a massive problem: it removed physical barriers to information. The core promise was, "Anyone with a browser can access information from anywhere."

We haven't stopped chasing that goal. We just wanted a level up.

Human Ambition and Season 2

Humans are never satisfied.

Men sat and thought: "If birds can fly, shouldn't we build a vehicle to do that?" "If fish can swim, shouldn't we build a vehicle to do that too?"

That exact mindset pushed the internet from Season 1 to Season 2. Web1 gave us the protocols and the connection, but human ambition always wants to go further. We wanted to move from just "publish and read” to “interact, share, and build together."

This birthed Web2: the "read-and-write" web.

Web2 didn't change the fundamental internet. It just brought our pictures, our videos, and our voices into the mix. But this caused a massive cultural shift. Why? Because suddenly, you weren't just consuming the information anymore. You became the information that other people consume.

The internet became highly interactive and social. But making ourselves the product came with a hidden cost we didn't fully understand at the time.

The Hidden Cost and the Web3 Fix

Web2 is amazing, but it is dominated by a few giant platforms. They store your data. They decide what gets shown or removed. They monetize your activity, keeping the profits while you create the value.

That is why people started pushing for Web3. We saw central gatekeepers raising issues of censorship. We saw privacy slipping away. People wanted more say over their digital identity.

For some reason, people try to detach Web3 from the internet, as if it's some completely alien technology. It's not. It is simply the next season of the exact same show, designed to fix a glaring structural problem.

Web3 uses new tech enablers like blockchain, decentralized storage, and peer-to-peer protocols, to introduce the "read-write-own" web.

Here is the progression:

Web 1.0 (Read-only): Companies publish, you consume.
Web 2.0 (Read-write): You interact, but platforms own the space and the data.
Web 3.0 (Read-write-own): You interact, but you own your data, your identity, and the value you create without a central intermediary.

Instead of data living on a few company servers, it's distributed. It's not a buzzword. It's a structural fix.

You Are An Internet Builder

I need to clear up a major misconception: Web3 is not at war with Web2 or Web1.

Do not see this as a competition. Web1 hasn't even faded away; every time you read a static webpage, you are using the fundamental internet. Web3 was birthed from the others. They all share the exact same DNA.

If Web3 promises to remove centralized gatekeepers, it means eventually, someone will find the gaps in Web3 and introduce the next innovation. Maybe Web4. You will find a pattern that they are just continuously filling the gaps the previous version left behind. It is one whole, continuous system.

This means if you can build in Web1, you can build in Web2, Web3, and whatever comes next.

There are endless possibilities. You don't have to box yourself in as just a "Web2 developer" or a "Web3 developer."

You are an internet builder.

The Engineering Method

Because the web shares the same DNA, you need to have a foundational knowledge of versions 1 and 2 to actually grasp what we are building in version 3. You can't build the future if you don't understand the past.

At BinnaDevLab, we see the endless possibilities of these new iterations. We train developers to understand this entire ecosystem strictly from an engineering method.

The internet is here to stay. It may have different versions, but do not confuse it. It is still the same internet. We are still connecting. We are still sharing resources. We are still processing data. We are just using better vessels.

The Internet is Here. Come to BinnaDevLab and learn how to grow this knowledge.

Before you go, I have a quick task for you: Google what "engineering method" is, and drop your findings in the comments below. Let's discuss it.

ERC20 Edge Cases Every Smart Contract Engineer Should Know

Obinna Duru — Mon, 22 Jun 2026 12:47:40 +0000

Your protocol launches. Everything passes the test suite with 100% coverage. Your audits are clean.

What went wrong?

Most ERC20 exploits are not actually bugs in the protocol's core logic. They happen because protocol engineers assume every token behaves exactly like a vanilla OpenZeppelin implementation.

Let's look under the hood of the most common ERC20 edge cases that break production systems, and how to engineer defensive architectures to mitigate them.

The Four Assumptions That Break Integrations

Before we look at specific edge cases, it helps to build a mental model of why these failures happen. Almost every ERC20 integration bug stems from one of four flawed assumptions:

Amount Assumptions: Believing the amount you request to transfer is the exact amount that will arrive.
Execution Assumptions: Assuming token transfers are passive state updates, rather than active execution environments.
Permission Assumptions: Believing that having a sufficient balance and allowance guarantees a transfer will succeed.
Accounting Assumptions: Hardcoding precision logic or assuming token behavior is immutable.

Let's break down how these assumptions fail in production.

Edge Case #1: Fee-on-Transfer & Rebasing Tokens

The assumption
If I call token.transferFrom(alice, vault, 100), the vault's balance increases by exactly 100.

What actually happens
Tokens can deduct a tax on transfer (e.g., a 5% protocol fee) or continuously alter user balances algorithmically (rebasing).

Example failure
A user deposits 100 fee-on-transfer tokens. The token takes a 5% fee.

User calls deposit(100)
👇
Token executes transfer, deducts 5% tax
👇
Vault receives 95 tokens

❌ Vault internally mints 100 shares based on 'amount' parameter
✅ Vault should mint 95 shares based on actual received funds

Mitigation
Never trust the amount parameter for internal accounting. Always measure the actual balance delta before and after the transfer.

uint256 balanceBefore = token.balanceOf(address(this));
token.safeTransferFrom(msg.sender, address(this), amount);
uint256 balanceReceived = token.balanceOf(address(this)) - balanceBefore;

// Use balanceReceived for all subsequent logic, never 'amount'
_mintShares(msg.sender, balanceReceived);

Takeaway: Balance-delta accounting fixes this assumption. Unfortunately, the next edge case breaks protocols even when the balances match perfectly.

Edge Case #2: Tokens with Callbacks (ERC-777 & Transfer Hooks)

The assumption
Calling transfer only updates storage balances and returns execution flow directly back to my contract.

What actually happens
Standards like ERC-777, or custom tokens with transfer hooks, actively hand execution control back to the sender or receiver via external calls during the transfer process.

Example failure
Your protocol updates the user's internal debt balance after pushing tokens to them.

User calls withdraw()
👇
Protocol calls token.transfer(user)
👇
Token calls back to User's smart contract
👇
User's contract calls withdraw() AGAIN (before protocol debt is updated)

This is a classic reentrancy attack, facilitated entirely by the token's internal hook.

Why This Surprises Engineers: We naturally view tokens as passive data ledgers. Callbacks turn tokens into active, hostile execution environments.

Takeaway: Reentrancy guards handle unexpected execution paths. But what happens when a token quietly fails without telling you?

Edge Case #3: Returning false vs. Reverting

The assumption
If a token transfer fails, the transaction will revert.

What actually happens
Some older tokens (like ZRX) do not revert on failure. Instead, they gracefully return a false boolean.

Mitigation
Never use bare transfer or transferFrom calls. Wrap them in logic that asserts the boolean return value is true.

OpenZeppelin / best practice
Always use OpenZeppelin's SafeERC20 library (safeTransfer, safeTransferFrom). It normalizes behavior by forcing a silent false failure to revert.

Takeaway: SafeERC20 forces silent failures to revert. But occasionally, you actually want certain transfers to bypass reverts.

Edge Case #4: Zero Address & Zero Amount Reverts

The assumption
Transferring an amount of 0 is a harmless No-Op (no operation) that costs a little gas but executes successfully.

What actually happens
Different token implementations handle zeros differently. Some explicitly revert if the transferred amount is 0, or if the target is the zero address.

Mitigation
Standardize behavior by wrapping transfers in a simple defensive check to bypass zero-amount logic.

if (amount > 0) {
    token.safeTransfer(user, amount);
}

Takeaway: Standardizing behavior protects your loops. But what if the token completely breaks the standard interface?

Edge Case #5: Missing Return Values (The USDT Problem)

The assumption
All ERC20 tokens return a boolean, as dictated by the standard interface.

Production Reality: Tether (USDT) on Ethereum Mainnet is non-standard. Its transfer, transferFrom, and approve functions do not return a boolean; they return void.

Example failure
If your contract compiles against the standard IERC20 interface, the EVM expects boolean return data to decode.

Standard: function transfer(...) returns (bool)
USDT:     function transfer(...) [returns void]
EVM:      "Wait, where is the boolean to decode? Revert."

Your protocol completely fails to integrate with the largest stablecoin on the market.

Mitigation
OpenZeppelin's SafeERC20 handles this under the hood. By using safeTransfer, you safely abstract away the missing return value issue at the assembly level.

Takeaway: SafeERC20 handles legacy interfaces. But interface compatibility won't save you from centralized control.

Edge Case #6: Blacklisted Addresses

The assumption
If an address has a sufficient balance and allowance, a transfer will always succeed.

What actually happens
Fiat-backed stablecoins like USDC and USDT maintain centralized blacklists. If an address is blacklisted, all transfers involving that address will revert.

Takeaway: Decoupling logic prevents centralized blacklists from freezing your protocol. Speaking of centralized quirks, let's look at approvals.

Edge Case #7: Non-Zero Approval Restrictions

The assumption
You can update an allowance from any number to any other number using approve(spender, newAmount).

Mitigation
You must approve 0 before approving the target amount. In OpenZeppelin v5+, safeApprove was removed. Use forceApprove(), which natively handles the 0 reset under the hood.

Takeaway: Approval races are tricky, but at least the token is always the token... right?

Edge Case #8: Multiple Addresses for the Same Token

What actually happens
Some tokens (like older TrueUSD implementations) use multiple entry point addresses that point to the same underlying state.

Mitigation
Identify tokens strictly by exact, whitelisted addresses. Never rely blindly on msg.sender to dynamically determine asset identity.

Takeaway: Identity is fluid. And worse, token logic is mutable.

Edge Case #9: Upgradeable Tokens

The assumption
The token behavior I test today will be the token behavior in production tomorrow.

Takeaway: You can't control token upgrades, but you can control how you calculate value. Which brings us to spot balances.

Edge Case #10: Flash-Mintable Tokens

The assumption
Massive token balances represent real, scarce capital.

Mitigation
Never rely on spot balances for price discovery or voting power. Use Time-Weighted Average Price (TWAP) oracles and historical checkpoints.

Takeaway: Spot balances lie. And sometimes, tokens lie about how much they transferred, too.

Edge Case #11: Transferring Less Than Requested

The assumption
If I request to transfer type(uint256).max, the token will either transfer that exact enormous amount or revert.

What actually happens
Some obscure tokens treat an amount parameter of type(uint256).max as a custom flag meaning "transfer all of the user's available balance."

Mitigation
Once again, balance-delta accounting saves the day. Never assume the requested amount is the executed amount.

Edge Case #12: High-Decimal Tokens

The assumption
Tokens either have 18 decimals (like ETH) or 6 decimals (like USDC).

What actually happens
Tokens like YAMv2 use 24 decimals.

Mitigation
Always dynamically read the decimals() function and normalize balances to a standard precision internally before performing complex math.

Bonus Edge Cases

Defensive ERC20 Integration Checklist

Before deploying any contract that touches external ERC20 tokens, verify your architecture against these rules:

Are you using SafeERC20? Never use bare .transfer() or .transferFrom().
Are you measuring balance deltas? Never assume amount sent == amount received.
Are you safe from reentrancy? Assume every token transfer is an external callback.
Are you using Pull-over-Push? Ensure a failing transfer only affects the specific user, not the broader system loop.
Have you normalized decimals? Do not assume 6 or 18 decimals.
Do you rely on spot balances? Ensure oracles and voting mechanisms cannot be manipulated via flash-mints.

Closing Thoughts

Smart contract engineering is deeply unforgiving because you are not just building software; you are building immutable financial infrastructure.

Treat every external token as fundamentally hostile. Rely on pure math, stateful invariants, and defensive accounting.

Reliable systems emerge from reducing assumptions. Let's build something we can trust.

What edge cases have caused problems in your own deployments? Let's chat about it in the comments below. Follow for more deep dives into smart contract architecture and onchain security.

How AMMs Work: The Simple Math Behind Decentralized Trading

Obinna Duru — Sat, 13 Jun 2026 06:00:00 +0000

One of the hardest problems in decentralized systems is this: how do two strangers trade without trusting each other or paying a middleman to coordinate?

In traditional finance, this is solved by centralized exchanges. On the blockchain, we solve it with an Automated Market Maker (AMM).

If you spend any time looking at decentralized finance (DeFi), you have probably seen the acronym floating around. Today, we are going to look under the hood to see exactly what an AMM is, why the Ethereum ecosystem desperately needed it, and how it translates market rules into unstoppable code.

The Constraint: Why Order Books Fail Onchain

Before we can appreciate the solution, we have to understand the architectural constraint.

In traditional finance (like the stock market or centralized crypto exchanges like Binance or Coinbase), trading runs on an Order Book.

An order book is a giant digital matchmaking list. If I want to buy 1 ETH for $2,000, I write my name on the list. The exchange then searches for someone willing to sell 1 ETH for exactly $2,000. When it finds a match, the trade executes.

This works flawlessly on centralized servers. But on a blockchain, order books have a fatal flaw: Cost.

Every single time you place, cancel, or match an order, it requires a state change on the network. State changes cost "gas" (transaction fees). If you had to pay a $20 gas fee just to list your trade on a decentralized order book whether someone buys it or not, the system would instantly become too slow and prohibitively expensive to use.

We needed a way to trade assets without a matchmaking middleman. We needed to replace human coordination with reliable computation.

The Analogy: The Potato & Apple Farmers

To understand how an AMM solves this coordination problem, let's use a simple system model.

Imagine you are a potato farmer. You have hundreds of potatoes. Eventually, you get sick of them and just want a crisp, sweet, red apple.

There are no grocery stores. To get an apple, you have to find an apple farmer who is tired of apples and wants potatoes, and trade with them directly. This is the exact equivalent of an Order Book-finding a direct match. It is exhausting.

Now, imagine an automated bin appears in the middle of your village.

A wealthy merchant came by and filled this bin with 100 apples and 100 potatoes. The bin has no human cashier. Instead, it is run by a simple mathematical formula. The formula's only rule is to balance the supply.

When you walk up to the bin and take out 20 apples, apples suddenly become scarcer. Because there are fewer apples left in the bin, the formula automatically raises the price of apples. To take those 20 apples, the bin demands you put in 25 potatoes.

Next time someone wants an apple, it will cost even more potatoes, because apples are getting rarer. But if an apple farmer comes along and dumps 50 apples into the bin to take out some potatoes, the price of apples drops back down.

That bin isn't intelligent. It doesn't predict markets. It simply enforces rules.

This automated, math-driven bin is the exact conceptual framework of an Automated Market Maker.

The Mechanism: The Constant Product Formula

In decentralized systems, that automated bin is called a Liquidity Pool. It is simply a smart contract holding a pool of two different tokens (like ETH and USDC).

Instead of waiting for an order book to match your trade, you trade directly against the smart contract.

But how does the contract know what price to charge you? It uses an algorithmic invariant. The most common one is the Constant Product Formula, which looks like this:

x * y = k

This math is beautifully simple and completely deterministic:

x is the amount of Token A (e.g., Apples).
y is the amount of Token B (e.g., Potatoes).
k is a constant number that must always stay exactly the same after a trade.

Let's use our 100 apples and 100 potatoes example.
100 (apples) * 100 (potatoes) = 10,000 (our constant 'k')

If you take 20 apples out of the pool, there are only 80 apples left. But the smart contract strictly enforces that the total multiplied together must still equal 10,000.

So, the contract calculates the new required state: 10,000 / 80 apples = 125 potatoes.

For the pool to satisfy the invariant, it must now contain 125 potatoes. Since it originally had 100, you have to deposit 25 potatoes (the difference between 125 and 100) to execute your trade.

That is it. Supply and demand, governed purely by unbreakable math. As one asset is bought out of the pool, it mathematically becomes more expensive. As an asset is sold into the pool, it becomes cheaper.

The Infrastructure: Liquidity Providers

This raises an engineering question: Where do the millions of dollars worth of tokens sitting in these smart contracts come from?

They come from Liquidity Providers (LPs).

LPs are everyday users, investors, or protocols who lock their own tokens inside the smart contract to fund the pool. In exchange for supplying this infrastructure, they receive an LP Token: a digital receipt proving they own a percentage of that specific pool.

Why would anyone risk their capital to let strangers trade against it?

Fees.

Every time a user makes a swap on an AMM, the protocol charges a tiny fee (usually around 0.3%). That fee does not go to a CEO or a centralized exchange. It goes directly back into the liquidity pool.

Because the LP tokens represent a percentage claim over the pool, as those trading fees pile up, the underlying value of the LP tokens increases. The Liquidity Providers earn a yield simply for providing the capital that makes decentralized trading possible.

Key Takeaways

Let's quickly recap the system architecture we just explored:

Order Books are inefficient onchain. Requiring a state change for every order creation and cancellation costs too much gas.
AMMs replace middlemen with math. You trade directly against a smart contract (a Liquidity Pool) rather than waiting for a human counterpart.
Prices are driven by deterministic algorithms. Using formulas like x * y = k, the AMM automatically raises the price of an asset as it becomes scarcer in the pool.
Liquidity Providers are the backbone. They supply the underlying tokens that make the system liquid, earning trading fees as a reward for their capital.

Final Thoughts

AMMs changed trading by replacing coordination with computation, turning market rules into software anyone can verify.

They took a complex, middleman-heavy financial process and reduced it to a few lines of self-executing, reliable code. They are a perfect example of how thoughtful engineering can create systems that are not only highly functional, but entirely trustless.

What are your thoughts on how AMMs are designed? Have you ever provided liquidity to a protocol yourself? Let's chat about it in the comments below.

Let's build something you can trust. Follow for more deep dives into smart contract architecture and onchain fundamentals.

Demystifying DevRel: What It Actually Is (And Why Should You Become One?)

Obinna Duru — Mon, 25 May 2026 06:00:00 +0000

If you spend enough time in the tech space, you will eventually hear the word "DevRel". You will see people with titles like Developer Advocate, Community Manager, or Developer Relations Engineer. They speak at conferences, write tutorials, hang out in Discord servers, and the community usually seems to love them.

But what exactly do they do? Is it just marketing for coders? Is it just customer support?

For me, DevRel is simply the combination of two words: Developer and Relationship.

If you have little to no knowledge of what Developer Relations is, this article will break down exactly what it means, what the day-to-day looks like, and help you decide if it is a career path you might want to pursue.

The "Developer" (The Builder)

A developer is a builder.

Someone who creates things from scratch or builds on top of existing infrastructure. Their goal is always to create something meaningful.

As humans, we naturally love creativity because it gives us variety, and variety is the spice of life.

Imagine I hand you a bag of flour. With creativity, you don't just see white powder. You see the potential to create bread, cake, doughnuts, and countless other pastries. Even with cake alone, there are endless flavors and styles.

That is the essence of creativity.

And that exact same creative spark lives in the heart of a builder. In software development, the "flour" is code, APIs, and infrastructure. They take raw technical ingredients and bake them into applications that change the world.

The "Relationship" (The Connection)

Now, let's talk about relationship.

A relationship is simply how people connect. And how do human beings connect? Through similarities.

We connect over shared interests, backgrounds, mindsets, experiences, or even just sharing the same birthday or hometown. If you meet a stranger today and find out they went to your high school, you naturally connect faster because you share common ground.

Bring that concept into DevRel.

A DevRel is someone who can genuinely relate to builders because they understand the realities of software development. They share common ground with them.

And what does that shared ground look like?

Designing and building systems
Dealing with broken deployments
Staring at a screen at 2 AM trying to debug an issue

The Elephant in the Room: "Do I need to code to be a DevRel?"

Because of this shared reality, people constantly ask: "Do I need to know how to code before becoming a DevRel?"

From my perspective, the answer is yes-at least to some level.

Developers can quickly detect inauthenticity. If you try to relate to a developer's struggle with a broken API, but you have never actually written a line of code or consumed an API yourself, the interaction falls flat.

You need to understand the language developers speak so you can communicate naturally and actually help them solve their problems. You don't need to be the absolute best 10x senior engineer in the room, but you do need to have built things.

What Does a DevRel Actually Do Daily?

Have you ever wondered what a Developer Advocate does when they log into their computer every morning? Typically, their daily tasks involve:

Writing Code & Content: Building demo applications, writing technical tutorials, and creating open-source templates so developers don't have to start from scratch.
Community Management: Hanging out in Discord or Slack, answering technical questions, and helping developers get unblocked.
Public Speaking: Giving technical talks at conferences, hosting webinars, or running hackathons.
Product Feedback: Listening to what frustrates the community and carrying that feedback directly to the internal engineering team to improve the product.

Developer Relations (DevRel) is a function that bridges the gap between developers and a product or platform. DevRels help developers succeed by providing education, tools, and support, while also feeding real-world developer feedback back into the product and engineering teams.

Why Does DevRel Exist? (The Bridge)

You might be wondering, if a company builds a great technical product, won't developers just use it?

Not necessarily. There are many reasons companies hire DevRel teams, but the major responsibility boils down to one word: Onboarding.

Whenever a new system, protocol, or infrastructure is created, developers need to understand four critical things before they will dedicate their time to it:

What it does.
How it works.
Why it matters (how it makes their life easier).
How they can use it (the actual code and implementation).

If a company has a brilliant product but terrible documentation and no one to answer questions, developers will leave.

That bridge between the raw technology and the human community is where DevRel lives.

They write the tutorials. They build the sample projects. They answer questions in the Discord server. And just as importantly, they listen to the developers' frustrations and carry that feedback back to the company's internal product team to make the tool better.

Is DevRel the Right Career For You?

DevRel is an incredibly rewarding path, but it requires a very specific hybrid of skills. It might be perfect for you if:

You love coding, but you also love talking about code. You enjoy building, but you enjoy teaching someone else how to build just as much.
You have high empathy. When someone is stuck on an error message, you don't feel annoyed; you feel a genuine desire to help them figure it out.
You are a translator. You can take a complex, intimidating technical concept and explain it simply to a beginner without making them feel stupid.
You love community. You actually enjoy the human side of tech.

Final Thoughts

At the end of the day, a good DevRel does not just market products. Marketing is about telling someone to buy something.

A good DevRel helps developers feel understood. They provide the ingredients, teach the community how to bake, and celebrate the amazing things the builders create. If you love technology and you love people, DevRel might just be the perfect place for you.

Are you currently thinking about transitioning into DevRel? What is your biggest question about the role? Let's chat in the comments below.

Smart Contracts Demand Better Infrastructure: Building on contract.dev

Obinna Duru — Sat, 23 May 2026 06:06:27 +0000

When you first start writing smart contracts on the EVM chains, your journey usually begins in Remix. It is a powerful, open-source web and desktop application for writing, compiling, testing, and deploying code, making it a fantastic tool for quick iterations and local simulations. But eventually, you outgrow it. Even with its robust features, a localized environment does not perfectly replicate how your contract will interact with live mainnet state.

To truly test a protocol, you move to a public testnet. This is where the engineering friction begins.

You suddenly need to set up an Alchemy or Infura account just to get an RPC URL. Then comes the faucet fatigue. You scour Discord or click traffic lights on web pages just to beg for a fraction of Sepolia ETH. Many faucets now require a minimum mainnet balance to prevent spam. This is a massive roadblock if you are following basic security practices.

To protect your real-world funds, you should never paste your primary wallet's private key into a local .env file where an accidental GitHub push or a malicious package could expose it. Instead, you use fresh, $0-balance "dummy" accounts. But when a faucet requires a mainnet balance, it breaks this safety measure, forcing you to either risk your real wallet or fund a dummy account with real money just to get testnet tokens. Others force you to connect your personal social media and tweet just to get a single drop.

If you are designing a system that requires multiple actors like a Client, a Provider, and an Arbiter in an Escrow, this friction multiplies. You either have to repeat this frustrating process for three separate wallets, or manually transfer tokens between them. And ironically, those manual transfers still cost you the precious testnet gas you just spent time trying to collect.

The testing infrastructure quickly becomes more exhausting than writing the actual architecture.

Recently, I began exploring ways to reduce this environmental friction and found a highly practical workflow using contract.dev. It provides the visual simplicity of a tool like Remix, but on a globally accessible, private EVM testnets that replay mainnet state and come with built-in tools for testing, analysing, and simulating smart contracts before launch.

Here is a look at how I approach testing a 3-actor Escrow system visually, eliminating local node overhead and faucet fatigue so I can focus purely on protocol behavior.

The Architecture: A Trust-Minimized Escrow

To demonstrate this workflow, I built TrustEscrow.sol. The architecture is designed to be reusable and relies on strict access control across three distinct roles:

Client: Funds the escrow.
Provider: Executes the work and receives the funds.
Arbiter: A neutral third party that resolves disputes.

Because the state transitions depend entirely on who is calling the function, verifying role transitions is critical. I explicitly designed this contract with a resetEscrow function to allow continuous lifecycle testing without needing to redeploy the contract. Here is the core state machine governing the escrow:

enum Stage {
    AwaitingFunding, // 0 - deployed or reset, waiting for client
    Funded,          // 1 - ETH held; work in progress
    Completed,       // 2 - client released funds; ready for reset
    Disputed,        // 3 - either party raised a dispute; arbiter needed
    Resolved         // 4 - arbiter settled dispute; ready for reset
}
Stage public stage;

(Note: Making the state explicitly public is a deliberate choice here, it allows visual dashboards to read and display the exact stage of the protocol later in the workflow).

Normally, verifying these transitions requires writing extensive .t.sol files with heavy vm.prank() overhead. Here is how we can verify them visually on a live network instead.

Step 1: The Instant Environment (No Alchemy, No Faucets)

The immediate relief of this workflow is the infrastructure. By creating a project on contract.dev, I was instantly handed a live Stagenet RPC URL. No third-party node providers required.

To test this escrow, I needed three distinct, funded wallets. Instead of configuring these locally or begging a public faucet, I used the platform's Wallet Generator to spin up accounts for the Client, the Provider, and the Arbiter.

Using the built-in Stagenet Faucet, I funded the Client's wallet with 100 ETH instantly. This is a live RPC that anyone in the world can interact with. You get the freedom of a public testnet without the artificial scarcity of testnet tokens.

Step 2: CI/CD Sync and Deployment

Unlike local nodes, the platform doesn't just guess your contract's ABI. By linking my GitHub repository, the platform's CI/CD pipeline automatically synced and compiled my Foundry project.

To deploy, I didn't have to learn a new framework. I simply opened my terminal and ran my standard Foundry deployment script (forge script), pointing it to the new Stagenet RPC and my newly funded wallet private key.

The moment the transaction confirmed on the network, the platform detected the deployed contract and automatically generated a Workspace: a dedicated visual dashboard perfectly mapped to my Solidity code.

(Crucial note for advanced developers: Unlike a local simulation, this Stagenet utilizes Mainnet Replay. It actively mirrors live mainnet state. If your contract interacts with live Uniswap liquidity or Chainlink oracles, you can test against those live states immediately without writing complex fork scripts).

Step 3: Verifying State Transitions

When testing architecture, immediate feedback is invaluable. Using the Account Impersonation feature directly from the dashboard UI, I impersonated the Client and executed the fundEscrow() transaction with 1 ETH.

The Workspace updated in real-time to reflect the new reality. Instead of relying on terminal queries or cast call commands, the dashboard visually confirmed that the contract balance was strictly locked at 1 ETH, and the stage variable had transitioned correctly from AwaitingFunding to Funded.

Continuing the simulation, I impersonated the Provider to raise a dispute, and finally the Arbiter to resolve it. The entire lifecycle of a complex 3-actor protocol was verified in seconds.

Step 4: Automating the Ecosystem (AI User Activity)

Manually clicking through a happy path is great for an initial sanity check. But what if you want to simulate a living, breathing protocol under continuous load? Normally, this requires writing complex Hardhat scripts or custom bots to continuously fire transactions and redeploy contracts.

This is where my workflow completely changed.

The platform includes an Activity Scheduler powered by AI. Instead of writing mock scripts, the AI reads your contract's source code, ABI, and storage layout, and designs realistic user personas for your specific protocol.

Because I built TrustEscrow to be reusable via the resetEscrow function, the AI was able to create infinite, continuous testing loops. With one click, it generated new dummy wallets, funded them, and scheduled recurring transaction workflows. In my Workspace, it automatically created two distinct, recurring timelines:

The Happy Path: It scheduled the Client to fundEscrow, releaseFunds, and resetEscrow every 20 blocks.
The Dispute Path: It scheduled a complex continuous workflow of fundEscrow -> raiseDispute -> resolveDispute -> resetEscrow every 30 blocks.

I didn't have to write a single line of testing script. I was able to sit back and watch the Stagenet process concurrent, multi-actor state transitions continuously.

Bridging the Frontend Gap

Beyond testing smart contract logic, this approach solves a very real integration problem.

When you build in Remix or on a local Anvil node, handing the protocol off to a frontend developer usually requires them to recreate your local environment just to build the UI.

Because a Stagenet is a persistent, globally accessible network, you can simply share the RPC URL with your frontend team. You hand them a live, fully-funded sandbox where the AI Activity Simulator is already generating realistic background traffic. They can begin building the interface immediately against predictable, living data.

Final Thoughts

Smart contracts handle real value, so engineering them requires a deep focus on security, invariants, and mathematical correctness. Testing infrastructure should support that focus, not distract from it.

While robust local environments are great for early iterations, serious architecture requires a production-like setting. Visual testing on a Stagenet makes it easier to observe protocol behavior, simulate concurrent user activity, and collaborate with your team without getting bogged down in RPC setups and faucet fatigue.

If you are tired of fighting local nodes to test multi-wallet architecture, I highly recommend integrating a visual Stagenet into your workflow.

You can view the full TrustEscrow architecture on my GitHub here: github.com/obinnafranklinduru/trust-escrow

📚 Glossary of Terms (For the Curious)

EVM (Ethereum Virtual Machine): The underlying engine that processes and executes smart contracts on Ethereum and other compatible blockchains. Web2 Analogy: Think of it like the global operating system or server environment (like Node.js or AWS) that runs your code.
RPC URL: The digital bridge that allows your interface to communicate with the blockchain. Web2 Analogy: Just like an API endpoint connects a frontend web app to a backend database.
Faucet: A developer service that provides free test tokens. Web2 Analogy: Like getting free "sandbox credits" in Stripe to test payments without using real credit cards.
Mainnet vs Testnet: Mainnet is the live network with real financial value. A testnet is a public sandbox with zero-value tokens. Web2 Analogy: Mainnet is your live "Production" environment. A testnet is your "Staging" environment.
Stagenet: A private testing environment that actively mirrors the live mainnet state. Web2 Analogy: A high-fidelity staging server that has been perfectly synced with a live copy of your production database.
Private Key: The secret cryptographic password that grants total control over a wallet and its funds. Web2 Analogy: The root password to your bank account.
.env File: A hidden local file used to store sensitive information securely. Web2 Analogy: It serves the exact same purpose in Web2—keeping API keys and passwords out of public GitHub repositories.
ABI (Application Binary Interface): A file that acts as a translation manual telling a frontend exactly how to interact with a compiled smart contract. Web2 Analogy: Like an OpenAPI/Swagger document that defines the endpoints and expected payloads for a REST API.
State Machine: An architectural pattern where a contract can only exist in one specific stage at a time (e.g., AwaitingFunding or Completed). Web2 Analogy: Like an e-commerce order that must strictly move from 'Pending' -> 'Shipped' -> 'Delivered' without skipping steps.
Foundry: A fast, specialized command-line toolkit used for compiling, testing, and deploying smart contracts. Web2 Analogy: A mix between a build tool (like Webpack) and a testing framework (like Jest).
vm.prank(): A specific testing command used to impersonate a different user to verify access controls. Web2 Analogy: Like a "Login as User" feature in an admin dashboard to test what a specific customer sees.

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.

DEV Community: Obinna Duru

Understanding Gas on the Blockchain: A Practical Guide Using Real Transactions

Separating the Five Core Concepts

Under the Hood: How Does the Blockchain Count Gas?

Case Study One: Calling increment() on Monad Testnet

Case Study Two: Inspecting a Transaction on Ethereum Sepolia Testnet

How Do You Know What Gas Limit to Set?

Understanding Gas Price and Gwei

Decoding EIP-1559: Base Fee, Priority Fee, and Max Fee

Why Do Transactions Need a Gas Limit? (And Why Gas Costs Change)

Comparing the Two Receipts: Are Fees on Monad Expensive?

Common Misunderstandings About Gas (Quick Checklist)

How to Explain Gas to Someone Else

Let's Figure Out the Rest Together

What the DAO Hack, Parity Freeze and Ronin Exploit Teach Us About Immutability

What "Deploying" Actually Means

Two Kinds of Trust

When Forever Goes Wrong

How Engineers Live With It

Every Escape Hatch Is Also an Attack Hatch

DYOR Is Not Just a Meme

Blockchain Isn't About Crypto. It's About a Trust Problem You Didn't Know You Had.

Why We Built BinnaDevLab Around This

What Actually Happens When Trust Breaks

What's Next

About BinnaDevLab

ERC20 Edge Cases Every Smart Contract Engineer Should Know

The Internet Hasn't Changed

Season 1: The "Read-Only" Web

Human Ambition and Season 2

The Hidden Cost and the Web3 Fix

You Are An Internet Builder

The Engineering Method

ERC20 Edge Cases Every Smart Contract Engineer Should Know

How AMMs Work: The Simple Math Behind Decentralized Trading

Demystifying DevRel: What It Actually Is (And Why Should You Become One?)

Smart Contracts Demand Better Infrastructure: Building on contract.dev

The Brief for the Judge: Writing Audit-Ready Documentation

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

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

Case Study One: Calling `increment()` on Monad Testnet