DEV Community: Obinna Duru

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.

From Promises to Proof: Designing a Defensive Escrow Protocol

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

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

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

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

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

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

The Mental Model: What is a Defensive Escrow?

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

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

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

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

The Math Problem: Why 10,000 Basis Points?

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

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

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

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

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

Why is this pie method so important? Stretch goals.

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

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

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

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

Graceful Failure: The "Abandoned" State

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

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

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

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

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

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

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

The Fiat Bridge: Bringing Web2 to Web3

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

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

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

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

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

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

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

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

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

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

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

Here is the distinction:

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

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

The BinnaDev Takeaway

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

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

Or, to put it in one line:

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

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