DEV Community: Obinna Duru

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.

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.

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.

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

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

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

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

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

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

We needed an upgradeable contract.

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

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

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

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

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

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

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

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

The Constructor Trap (And How to Get Hacked)

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

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

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

To prevent this, my approach is strict:

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

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

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

Storage Management: The Giant Spreadsheet

Upgradeable contracts are notorious for "storage collisions."

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

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

To prevent this, my approach is conservative and explicit:

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

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

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

The Hardest Lesson: Hunting for Ghosts

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

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

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

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

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

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

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

The BinnaDev Takeaway

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

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

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

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

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

Deployment Update

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

Here are the core deployment details:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// From src/types.ts

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

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

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

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

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

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

// From src/storage.ts

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

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

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

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

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

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

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

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

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

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

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

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

// From src/contract.ts

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

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

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

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

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

  return hash;
}

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

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

// From src/contract.ts

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

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

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

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

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

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

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

Repositories:

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

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

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

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

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

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

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

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

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

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

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

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

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

Traditional Resume vs. Onchain Protocol

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

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

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

The Analogy: Imagine a Digital Award Ceremony.

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

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

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

Therefore, the protocol enforces a two-step lifecycle:

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

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

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

A Look at the Code

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

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

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

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

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

Making it "Soulbound"

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

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

Engineering Excellence: Testing

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

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

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

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

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

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

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

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

📚 Beginner's Glossary

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

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

Engineering Trust: My Journey Building a Decentralized Stablecoin

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

"Smart contracts handle real value."

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

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

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

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

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

An Exogenous, Crypto-Collateralized, Algorithmic Stablecoin.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

To prevent this, we have Liquidators.

Think of Liquidators as the protocol's cleanup crew.

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

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

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

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

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

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

I implemented a check in OracleLib:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Link to GitHub Repo

Let's build something you can trust.

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

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