This post maps out four layers of vulnerability: code-level, composability-level, human-level, and external. Each has its own threat model, its own mitigations, and its own failure modes. The transitions between the levels are often fuzzy and overlapping, and sophisticated attacks span multiple layers. The core point of this post is that code is not the most important layer any more.

There are excellent resources for code-level and composability-level vulnerabilities. The OWASP Smart Contract Top 10 shows what vulnerabilities have been fashionable over the last couple of years. The Ethereum Enterprise Alliance has a useful specification outlining security considerations that should be made for smart contracts. These are useful but are not the full story. Let’s walk through the four layers of vulnerability.

1. Code-level Vulnerabilities

The bugs that can live inside a single contract are well-understood, well-documented, and increasingly well-mitigated. Developers, auditors, and tooling are all better than they were when Ethereum launched.

Reentrancy is a classic. A contract calls out to an external address before updating its own state, and the external address calls back in before the first execution completes. The result is that the contract’s state is stale during the callback, which can cause havoc. The fixes (checks-effects-interactions, mutexes) are standard practice.

Over- and underflows were a serious hazard in Solidity before 0.8.0, when arithmetic silently wrapped around. A balance that should have reached zero would instead wrap to 2^256. OpenZeppelin’s SafeMath library was the canonical fix. Solidity 0.8.0 made SafeMath unnecessary here by building in overflow checks.

Poor access control covers a broad category. Functions that should be owner-only but are not, admin roles that are never revoked, initialiser functions left callable after deployment. A missing onlyOwner modifier is embarrassingly simple to overlook and has cost projects millions.

Unbounded loops do not steal funds directly, but they can make a contract permanently non-functional. A loop that iterates over a list that grows with usage will eventually hit the block gas limit and brick the contract.

Delegate calls to untrusted contracts are a subtler hazard. delegatecall executes foreign code in the context of the calling contract’s storage. If the logic contract is upgradeable or untrusted, the storage layout can be corrupted or overwritten entirely.

Mitigations at this layer

The good news is that these vulnerabilities are pretty much solved by good engineering discipline today. Contract libraries such as OpenZeppelin and Solady provide battle-tested implementations of common patterns, Hardhat and Foundry make testing straightforward. There are mature static analysis tools and there is an excellent audit industry. Bug bounty programmes and the opportunity to buy exploit insurance provide a backstop. None of this is perfect, but code-level issues are far less likely to surprise a careful team than they were even five years ago.

What is perfect, within its limited scope, is formal verification. For teams that need the highest assurance, formal verification tools such as Halmos can mathematically prove that code invariants hold across every possible function input. They require significant additional effort but deliver mathematical certainty.

2. Composability-level Vulnerabilities

This layer is where contracts call other contracts, either within a single protocol or across the wider DeFi ecosystem. Composability creates risk. When protocols call other protocols, and those protocols call yet others, the attack surface is not a single contract. It is a graph of interacting systems with emergent behaviour that no single audit can capture easily.

Sandwich attacks exploit the fact that the public mempool is, well… public. An attacker sees your pending swap transaction, places a buy order immediately before it (pushing the price up), lets your transaction execute at a worse price, then sells immediately after. The attacker profits from the price impact your trade creates.

Oracle manipulation is a very popular attack. Protocols that rely on on-chain price feeds, particularly those using DEX spot prices, are vulnerable to attackers temporarily distorting the price through a large trade or flash loan. The protocol reads the manipulated price and makes decisions (lending, liquidation thresholds) based on bad data. Time-weighted average prices and multi-source aggregation are the standard defences.

MEV (Miner Maximal Maliciously Extractable Value) is where block proposers can reorder, insert, or censor transactions within a block. At the benign end this is arbitrage. At the hostile end it is front-running and sandwich attacks at scale.

Whale-controlled governance is a governance-layer risk. When token voting determines protocol upgrades, a sufficiently large holder, or a coalition, can pass proposals that benefit themselves at the expense of other users.

Mitigations at this layer

Fuzzing tools (Echidna, Medusa) catch emergent state violations that unit tests miss. Foundry also has invariant fuzzing built in, making it accessible if you are already using it for testing. Threat modelling (sitting down and systematically asking “what can an adversary do if they control this input?”) is a valuable technique. Audits can focus on contract interactions, not just the safety of single contracts. Bug bounties provide mitigation in this layer too. To avoid sandwich attacks and MEV, there is the option to not use the public mempool, and instead use MEV Blocker services, essentially private mempools.

As protocols become more cross-chain and more deeply composed, this layer gets harder, not easier.

3. Human-level Vulnerabilities

This layer covers human and operational risk. Where the previous layers involve code and systems, this one is about the people who design, build, deploy, and run the protocol and the processes around them.

OpSec failures around process approvals and key management are a consistent source of trouble. Lost keys, compromised keys, keys that were “just temporarily” on a hot machine. For any meaningful treasury, keys should not exist on any networked device, and changes should not require approval from a single signatory (as Wasabi Protocol demonstrated recently). Fireblocks and other institutional-grade wallet and multi-signature solutions provide significant protection (as explained in an earlier post).

Phishing and social engineering targeting team members, particularly those with signing authority, are increasingly sophisticated. Attackers research their targets, spoof credible communications, and create urgency. Bybit is a high-profile case that involved multiple vulnerability types, including social engineering and a supply-chain attack. NCC Group’s technical post-mortem is a thorough account of how it unfolded.

Faulty business logic is hard to catch in testing. Imagine a system built to deliver certain business logic, and that business logic is fundamentally wrong, say a pricing algorithm. All your tests will pass as green to successfully show you’re delivering that business logic, but that business logic is not correct.

Corruption and coercion are real risks for projects that are sufficiently valuable and whose key holders are publicly known. The “wrench attack” is not just a meme.

Poor audit processes are common. Projects skip audits due to cost or timeline pressure, audit only part of their codebase, or add “tiny fixes” to the audited code and put that amended code live instead. Contracts that are out of scope (multisigs, bridges, peripheral contracts) are often where the actual exploit lands.

Launch-targeted scams consistently target the moment of maximum attention: token launches, high-profile protocol announcements, airdrops. The larger the event, the more sophisticated the social engineering campaign surrounding it.

Hiring practices matter more than they might appear. A team with good security instincts, appropriate scepticism about unusual requests, and a clear understanding of what signing authority means is a different proposition from one without. Avoid recruiting from the TraderTraitor alumni network, even though they are clearly very skilled.

Address poisoning deserves a mention. An attacker sends tokens from a carefully crafted address that resembles a known address (matching prefix and suffix) with the goal of polluting your transaction history. When you next go to copy an address from your history, you select the poisoned one. I wrote about this in an earlier post.

Mitigations at this layer

Hardware wallets and a good quality multi-signature approval process for transaction signing. Security training for the whole team, not just engineers. Thorough audit scoping. If you have processes involving bridges, they are in audit scope. Response readiness matters here too: drills, documented incident response runbooks, and relationships with legal counsel. SEAL-911 is a free, round-the-clock emergency hotline staffed by vetted white-hat security researchers.

4. External Vulnerabilities

The final layer covers risks that originate outside your project, outside your immediate control, yet can still destroy your protocol.

Stablecoin depeg or collapse is a real thing. Terra/LUNA showed that foundational DeFi infrastructure can simply stop existing, and every protocol depending on it goes with it. Protocols built on top of stablecoins inherit that counterparty risk.

Supply-chain attacks target the developer toolchain itself: npm packages, build scripts, CI/CD pipelines, compromised dependencies. An attacker who can modify your build artefact before deployment wins regardless of how good your Solidity is. The KelpDAO exploit in April 2026, in which attackers replaced go-ethereum node binaries to approve a fraudulent cross-chain transfer, is a recent example of this class.

Nation-state and advanced persistent threats are no longer theoretical. Nation-state actors have pulled off multi-stage attacks combining technical exploits with social engineering, and the resources behind them are substantial.

Reputational risk is technically external but practically devastating. An exploit, even one from which funds are fully recovered, can permanently damage the credibility of a protocol. Recovery speed and communication quality matter as much as the technical response.

Mitigations at this layer

On-chain monitoring (Hypernative, Forta, and similar) can catch anomalous behaviour early enough to pause contracts before an exploit completes. Secure development practices throughout the supply chain (dependency pinning, reproducible builds, CI artefact signing) reduce the surface for supply-chain compromise. Response readiness: drills, pre-agreed pause procedures, relationships with exchanges and other protocols for coordinated response.

The Takeaway

Smart contract vulnerabilities are not a single problem. They are four overlapping problems:

The code-level layer has historically got the most attention. The human-level and external layers are where equally costly failures happen. A team that is rigorous about all four is doing real security work.

AI and vulnerability detection

A trend worth watching across all four layers is, unsurprisingly, AI. A recent a16z report explains how AI is becoming very good at identifying smart contract vulnerabilities, including composability-level bugs that are harder for humans to trace manually, but it is still not great at exploiting them unaided. The same capability that helps defenders scan for vulnerabilities is also lowering the bar for attackers.

We’re going to disassemble the bytecode of a Solidity smart contract call by hand, using pen and paper. By the end you’ll have a much better understanding of how EVM contract calls are executed. You can think of this as “Let’s play EVM!” because we will do with pen and paper what the EVM does at execution time.

First some terminology:

• Decompiling is the process of attempting to reconstruct high-level source code like Solidity (or any other higher level language) from compiled bytecode. This is complex and lossy, and may not produce perfect results due to compiler optimisations. We’re not doing this.
• Disassembling is the process of converting bytecode into human-readable opcodes, the mnemonic assembly instructions. This provides a direct, one-to-one mapping of the low-level instructions exactly as executed on-chain. This is what we are doing. We’re going to “be the EVM” with our pen and paper.

Right, so what contract shall we use? The SimpleStorage contract is Solidity’s “Hello World”. It is a minimal smart contract that stores and retrieves a single number. It’s the first contract most developers encounter when learning Solidity, so it makes a pretty good place to start.

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

contract SimpleStorage {
    uint256 public storedData;

    function set(uint256 x) public {
        storedData = x;
    }

    function get() public view returns (uint256) {
        return storedData;
    }
}

You might think that such a simple contract would compile down to just a handful of opcodes, but the compiler generates a lot more than just “read from storage” and “write to storage” operations. The compiler produces a complete runtime environment with a jump table for function dispatching, calldata validation, free memory pointer initialisation, return data encoding, and contract metadata.

So, we’re going to disassemble the bytecode and walk through every opcode for a particular function call, understanding what the compiler generates and why.

2. Preparation

2.1 Getting the Deployed Bytecode

We need to get the deployed bytecode for our SimpleStorage contract. You can do this any number of ways, from Hardhat, Foundry, Remix, Etherscan, or you can just use the bytecode below:

0x6080604052348015600e575f5ffd5b5060043610603a575f3560e01c80632a1afcd914603e57806360fe47b11460575780636d4ce63c146068575b5f5ffd5b60455f5481565b60405190815260200160405180910390f35b60666062366004606e565b5f55565b005b5f546045565b5f60208284031215607d575f5ffd5b503591905056fea26469706673582212203783f150f7f3854fe044645ed783cffbe5e53007e7bf25fc7d84255994d8a28f64736f6c634300081e0033

To produce the above, I used Foundry to build locally (with optimiser enabled and runs 200) and then forge inspect SimpleStorage deployedBytecode.

Notice that it is important to get deployedBytecode, not just bytecode. We want the bytecode as finally deployed on chain (the deployedBytecode), which is the code that subsequent transactions are executed against. We do not want the bytecode used by the initial contract deployment transaction (the bytecode) because that contains extra boilerplate to do the contract creation, which we’re not exploring here.

2.2 Getting some Transaction Data

Our path through the bytecode is determined by what function is called. This means we need some transaction data. In this example, we’re going to look at what happens when we call the set(uint256) function with a value of 42 decimal.

Using Foundry, we can work out what the transaction calldata should be, but of course you can do the same in Etherscan or other tools:

$ cast calldata "set(uint256)" "42"
0x60fe47b1000000000000000000000000000000000000000000000000000000000000002a

The first 4 bytes (0x60fe47b1) are the function selector. The remaining 32 bytes are the parameter value of 42, which is 0x2a in hex padded to 32 bytes.

2.3 Following along in the EVM Codes Playground

My original goal was to do this entirely with pen and paper. In practice, this is quite tricky. If you make one tiny mistake, say swapping the wrong stack entries, it breaks all the subsequent interpretation you do. A happy medium is to follow along in the EVM Codes Playground. Perform each instruction with pen and paper then follow up by checking you were right using the playground.

Paste both the bytecode and calldata into the EVM Codes Playground and click “Run”. You’ll see something like this:

Notice how the playground doesn’t automatically execute the whole transaction. It just brings up the opcode list and lets us step through opcodes one at a time. The playground also keeps a live view of the stack, memory and storage.

2.4 Opcode Reference

The opcodes we will encounter, and what they read and write to the stack, are listed here.

• Printable hardcopy reference
• Interactive online list

3. Let’s Play at Being an EVM!

If you want to follow along with pen and paper, you can print off this hardcopy opcode listing of the program, ready to annotate by hand. The final bytes in the listing are metadata (compiler version and so on) and are not executable, so we skip them.

3.1 Orientation

• Number Convention. When we play at being the EVM it makes sense to be using hex natively. The EVM does that, and it saves us a lot of writing of 0x. So in this section and all images, whenever you see a number, mentally prefix it with 0x. For example if you see 20 written, that means 0x20 which is decimal 32d.

• The Program Counter. Abbreviated PC, the program counter is the zero-based hex index of the next operation to be executed, starting at the first byte of bytecode which is PC 00.

• Everything is Stack Based. The EVM uses the stack to store temporary variables and hold the inputs and outputs to opcode operations. The stack can hold 1024d values, each 32d bytes, but only the first 16 or 32 values are currently easily accessible by opcodes¹.

3.2 Common Patterns

• PUSH and POP Operations are common. The POP opcode just discards the top of the stack. The PUSH1 to PUSH32 family of opcodes pushes a value of between 1d and 32d bytes onto the stack, where those byte values follow immediately in the bytecode. You’ll see plenty examples of this in our walkthrough.

• Conditional Control Flow with JUMPI. There is only ONE conditional control flow opcode and that is JUMPI. Any higher level language constructs like if statements or looping are compiled into patterns of opcodes with JUMPI. The JUMPI opcode pops two values from the stack, the first is the jump destination, which is an absolute program counter index (PC). The second value is the conditional value to be checked. If that second value is non-zero, then we jump to the destination, otherwise we continue to the next opcode. We can think of JUMPI as “jump if true”, where zero means false and non-zero means true.

3.3 Let’s Go!

Here’s the recipe we need to follow:

1. Look at byte of current PC. Example: PC 00 has the byte 60. Remember we’re all in hex now.
2. Translate byte to its opcode mnemonic. Example: 60 means PUSH1. Use our earlier opcode reference to help here.
3. Perform that operation. Example: for PUSH1 we must read the byte at the next PC and push it to the stack. PC 01 has value 80 so that value 80 gets pushed to the top of the stack. Again, use the opcode reference to see what to do.
4. Increment PC and go to step 1.

A critical part is to keep the stack accurately recorded, and there is a dedicated stack column in the hardcopy opcode listing. Following the above recipe for the first few PCs you should be ending up with something like this:

4. Notable Opcode Blocks

4.1 Free Memory Pointer Initialisation

The first 3 opcodes set up the free memory pointer.

[00] PUSH1 80    <-- push 80 to stack
[02] PUSH1 40    <-- push 40 to stack
[04] MSTORE      <-- store 80 at memory position 40

The EVM has a temporary memory area, separate from persistent storage, that contracts use during execution. By convention, memory position 40 holds a pointer to where free memory starts. The compiler sets it to 80, leaving the first 128d bytes reserved for special purposes like hashing.

4.2 Checking for Value Sent

[05] CALLVALUE   <-- get ETH sent with this call
[06] DUP1        <-- duplicate it
[07] ISZERO      <-- is it zero?
[08] PUSH1 0e    <-- push jump destination 0e
[0a] JUMPI       <-- jump past the revert if zero (good path)
[0b] PUSH0       <-- revert data offset
[0c] PUSH0       <-- revert data length
[0d] REVERT      <-- reject the transaction

None of our functions are payable, so any ETH sent with the call has to be rejected. CALLVALUE gives us the amount. Zero means we jump to 0e and carry on. Anything else hits REVERT and the transaction is rejected.

Worth noting the PUSH0 opcode (5f) here. Introduced in EIP-3855, it is a cheaper alternative to PUSH1 00 for pushing zero onto the stack.

4.3 The Jump Table (Function Dispatcher)

The jump table figures out which function to call. It starts by checking we have at least 4d bytes of calldata (enough to hold a function selector).

[0e] JUMPDEST
[0f] POP              <-- clean up from callvalue check
[10] PUSH1 04         <-- minimum 4d bytes needed
[12] CALLDATASIZE     <-- how many bytes did we get?
[13] LT               <-- fewer than 4d?
[14] PUSH1 3a         <-- revert destination
[16] JUMPI            <-- jump to revert if too small

Then it extracts the function selector from the first 4d bytes of calldata.

[17] PUSH0            <-- load from position 0
[18] CALLDATALOAD     <-- load first 32d bytes of calldata
[19] PUSH1 e0         <-- 224d bits
[1b] SHR              <-- shift right 224d bits, leaving the first 4d bytes

Then it compares the selector against each known function in turn.

[1c] DUP1
[1d] PUSH4 2a1afcd9   <-- storedData() selector
[22] EQ
[23] PUSH1 3e
[25] JUMPI            <-- jump to storedData() if match
[26] DUP1
[27] PUSH4 60fe47b1   <-- set(uint256) selector
[2c] EQ
[2d] PUSH1 57
[2f] JUMPI            <-- jump to set() if match
[30] DUP1
[31] PUSH4 6d4ce63c   <-- get() selector
[36] EQ
[37] PUSH1 68
[39] JUMPI            <-- jump to get() if match
[3a] JUMPDEST
[3b] PUSH0
[3c] PUSH0
[3d] REVERT           <-- no match, revert

The selectors are checked in ascending numerical order (2a..., 60..., 6d...). As I covered in an earlier post, whichever function is matched first costs slightly less gas to call.

4.4 The set() Function

The set() function implementation lives at PC 57. Before jumping to the calldata decoder, the compiler pushes the return addresses it will need later onto the stack.

[57] JUMPDEST
[58] PUSH1 66         <-- final return destination (after set completes)
[5a] PUSH1 62         <-- where the decoder should return to
[5c] CALLDATASIZE     <-- calldata size
[5d] PUSH1 04         <-- offset past the 4d-byte selector
[5f] PUSH1 6e         <-- calldata decoder address
[61] JUMP             <-- jump to decoder

The decoder (covered below) validates and extracts the uint256 parameter, then jumps back to 62.

[62] JUMPDEST         <-- decoder returns here, value is on the stack
[63] PUSH0            <-- storage slot 0
[64] SSTORE           <-- write value to storage
[65] JUMP             <-- jump to 66
[66] JUMPDEST         <-- valid jump destination
[67] STOP             <-- we are done, execution is completed successfully

SSTORE at PC 64 is doing all the real work. Everything else is scaffolding.

4.5 The Calldata Decoder

The decoder at PC 6e validates that at least 32d bytes of parameter data are present, then loads and returns the value to the caller.

[6e] JUMPDEST
[6f] PUSH0
[70] PUSH1 20         <-- expect 32d bytes of parameter data
[72] DUP3             <-- calldata size
[73] DUP5             <-- calldata offset
[74] SUB              <-- actual bytes available for params
[75] SLT              <-- signed less than 32d?
[76] ISZERO
[77] PUSH1 7d
[79] JUMPI            <-- jump to 7d if ok, fall through to revert if not
[7a] PUSH0
[7b] PUSH0
[7c] REVERT
[7d] JUMPDEST
[7e] POP
[7f] CALLDATALOAD     <-- load the uint256
[80] SWAP2            <-- tidy up stack
[81] SWAP1
[82] POP
[83] JUMP             <-- return to caller

Signed comparison (SLT) is deliberate here. A malformed calldata offset could produce a negative result from the subtraction, and SLT catches that where unsigned LT would not.

5. Wrap up

So there you have it. Our super simple contract turned into dozens of opcodes once compiled:

• Free memory pointer setup — initialising the EVM memory system
• Payability check — rejecting ETH if functions aren’t payable
• Function dispatcher — matching function selectors and jumping to implementations
• Parameter decoding — extracting and validating calldata
• The actual logic — one SSTORE

The compiler does lots of work to turn our high-level Solidity into safe, functional EVM bytecode. Understanding what’s happening under the hood helps you write more efficient contracts and makes debugging a lot easier when things go wrong.

5.1 Further work

You can experiment with this yourself by changing the SimpleStorage contract and seeing how the opcodes change. Try adding an event, or making a function payable, or making a call to an external contract. Each change will show you more about how the compiler works.

Making a call to an external function has a significant impact. When a call is made to an external contract, a new “call frame” is created, with a clean new stack, new memory, yet storage remains shared (remember it is keyed on contract and slot number). Perhaps this is something for a future article.

Footnotes

AI and agentic development are powerful force multipliers, allowing teams to do more with less. There is a risk, however, that many small agent-led changes gradually produce systems that are functional, but fragile. The knowledge of why the final system is shaped the way it is can end up living nowhere, because no human ever held the whole thing in their head. These systems can start to resemble Rube Goldberg machines:

Rube Goldberg was an American cartoonist famous for drawings of absurdly over-engineered machines that performed simple tasks through a chain of unnecessarily complicated steps. The machines worked, they just worked in a deeply convoluted way.

Why could this happen?

This risk is not unique to AI. Incremental software delivery has always had a tendency to optimise locally and drift globally. Agentic development just increases the speed and scale at which that can happen.

In an all-human team, new features are usually added with some regard for what is already there. Good teams often carry cross-domain knowledge and enough architectural context to notice when the whole system is starting to wobble. They get an uneasy feeling when code starts to smell. That kind of complexity minimisation requires judgment, not just technical capability.

By contrast, when an agent takes a ticket from spec to go-live, it is usually optimised to complete the task successfully, not to minimise long-term system complexity. It rarely steps back and asks whether the whole approach should be rethought. Agents do not get that uneasy architectural feeling, they focus on satisfying the task and passing the available checks.

A Rube Goldberg machine is not built in a single ticket. It forms gradually over time, largely because the path of least resistance for an agent is additive. When something does not work, it adds a wrapper, a retry, a duplicate table, or a translation layer. Without a holistic view, that is how a contraption emerges.

So what can we do?

Can’t we just specify more?

Specs written by humans are often under-specified in the ways that matter most here. They describe what much more readily than how. An agent filling in the gaps can make locally reasonable decisions that become a contraption when viewed globally, especially across tickets written by different people at different times.

Asking an agent in prose to “always consider the high-level architecture” might help, but it can just as easily be ignored. What helps more is turning architectural intent into checks that fail loudly.

Add guardrails

Guardrails are automated checks that enforce constraints on what an agent can produce. These are not suggestions in prose, they are hard failures that block progress until resolved. A guardrail does not get forgotten or quietly deprioritised. It fails the build. Guardrails in prose invite being completely ignored. This is evident in the sad tale of a production database being deleted, where the AI chose to ignore every single prose guideline it was given.

In practice, guardrails might look like:

• Complexity limits: a CI step that fails if a single PR touches more than a set number of files, or introduces more than a set number of new abstractions.
• Architecture fitness functions: automated tests that verify structural rules, such as “no module in layer A may import from layer C” or “all database access must go through the repository layer”.
• Critic agents: a second agent whose sole job is to review the output of the first, specifically asking “does this need to exist?” rather than merely “does this work?”.
• Refactor gates: a rule that triggers a mandatory human architecture review after every N agent-written tickets ship, before the next batch can begin.

The key property of a guardrail is that it makes unwanted complexity a first-class failure condition rather than an afterthought. If the agent’s solution is too complicated, it does not merge. The agent must either find a simpler approach or escalate to a human.

Guardrails help, but they do not remove the need for architectural ownership. Someone still needs to care about the shape of the system.

Does it even matter?

You could argue that this kind of technical debt does not always matter, and in some cases that is true. We may be entering a strange period in which some forms of technical debt become cheaper to rewrite or paper over, because AI reduces the cost of change.

Even so, for live and business-critical systems, that can be a risky bet. The faster a team can ship complexity, the easier it is to create a system that nobody can safely change.

Summary

The risk is not simply that AI agents write bad code. It is that they can produce locally good changes that accumulate into globally incoherent systems. The velocity of agentic development means teams can now build very large, very tangled contraptions before anyone notices. The defence is to put guardrails in place that make architectural drift and unnecessary complexity first-class failure conditions.

In traditional finance, Delivery Versus Payment (DVP) means the settlement of securities so that delivery only occurs if payment occurs. If we extend that to a blockchain, we can think of a smart contract that arranges atomic swaps of multiple assets between multiple parties. For example, a combination of ETH, ERC-20 tokens and ERC-721 tokens all moving between multiple parties in a single transaction. Either everyone gets what they are owed, or no transaction occurs at all.

We can imagine gold being exchanged for some land in the Wild West, where the exchange is simultaneous. Both parties seem pretty happy with the deal:

The full smart contract repo is here and is open-sourced under the MIT license. The smart contracts allow a single “exchange event” (a “settlement”) to be carried out between an arbitrary number of parties with an arbitrary number of different assets, including Ether, ERC-20 tokens and NFTs.

Let me try it!

Live UIs are available at:

• dvp.works
• dvpeasy.trade (coming soon)

The UIs share the same permissionless backend contracts, but have a different look and feel. Anyone can create a new UI on top of these contracts.

Delivery versus Payment Smart Contract Features

1. No fees other than cost of gas.
2. Non-upgradeable, singleton Delivery Versus Payment contract, minimizes trust required. Contracts audited by ShadowyCreators team.
3. Allows atomic swaps of an arbitrary number of assets between an arbitrary number of parties. No party risks sending assets without receiving what is promised (or getting their assets back).
4. Permissionless, anyone can create and execute these swaps, so long as the from address parties have approved.
5. Supports assets including native ETH, ERC-20 and ERC-721.
6. Optional auto-settlement, the final approving party can trigger auto-processing of the settlement.
7. Helper contract provides search functionality for off-chain use.
8. Anyone can create and host a UI for the same set of deployed contracts, or can deploy more contracts.

Interesting Solidity Features

There is no Owner

The permissionless nature of the contract was a design choice we made to ensure the contract would be useful to other projects. This means no settings that onlyOwner can change, which contributed to why we chose to not limit the sizes of settlements. There are many loops through unbounded arrays, by design, the idea being that each chain’s block gas limit will provide a natural maximum size. Settlements of around 100 to 200 asset movements between parties should be fine.

Handling Reverts during Auto-Settlement

An interesting detail behind the auto-settlement feature was how to handle cases where settlement execution failed. Auto-settlement is triggered by a party being the last approver, and if settlement execution failed we don’t want the approval to also fail — we still want the overall EVM transaction to succeed while acknowledging that the execution itself can fail. Like other languages, Solidity has a try-catch construct, but unlike other languages it also warrants a 40-page write up about the nuances of using it.

One of those nuances drove a structural decision: Solidity’s try{} only supports external or public function calls. This meant the actual settlement execution logic had to be extracted into a dedicated external function, executeSettlementInner, which guards itself by reverting if the caller is not the DVP contract itself. This inner function is then called via try in two places: inside approveSettlements() for auto-execution, and inside the public executeSettlement() for manual execution. In the auto-execution case, a failure is swallowed (the approval remains, the settlement can be retried); in the manual case the error is re-thrown so the caller gets a proper revert. The same three failure events are emitted in both paths, with an autoExecuted boolean parameter to distinguish which path triggered the failure. We simplified the catch clauses to cover three broad cases of reverts:

    // For any settlement: if we're last approver, and auto settlement is enabled, then execute that settlement
    for (uint256 i = 0; i < lengthSettlements; i++) {
      uint256 settlementId = settlementIds[i];
      Settlement storage settlement = settlements[settlementId];
      if (settlement.isAutoSettled && isSettlementApproved(settlementId)) {
        // Failed auto-execution will not revert the entire transaction, only that settlement's execution will fail.
        // Other settlements will still be processed, and the earlier approval will remain. Note that try{} only
        // supports external/public calls.
        try this.executeSettlementInner(msg.sender, settlementId) {
        // Success
        }
        catch Error(string memory reason) {
          // Revert with reason string
          emit SettlementExecutionFailedReason(settlementId, msg.sender, true, reason);
        } catch Panic(uint256 errorCode) {
          // Revert due to serious error (eg division by zero)
          emit SettlementExecutionFailedPanic(settlementId, msg.sender, true, errorCode);
        } catch (bytes memory lowLevelData) {
          // Revert in every other case (eg custom error)
          emit SettlementExecutionFailedOther(settlementId, msg.sender, true, lowLevelData);
        }
      }
    }

There is a corresponding mock Solidity contract for testing, that triggers each of these revert cases:

  /// @dev The `amount` parameter controls the behaviour of the function as follows:
  /// - If `amount == 1`: The function will revert with a revert string: "AssetTokenThatReverts: transferFrom is disabled".
  /// - If `amount == 2`: The function will revert with a custom error: `ThisIsACustomError()`.
  /// - If `amount == 3`: The function will trigger a panic due to a divide-by-zero error, causing the transaction to fail unexpectedly.
  /// - If `amount >= 4`: The function will revert with no message, using inline assembly to revert the transaction.
  function transferFrom(address, address, uint256 amount) public override returns (bool) {
    dummy = 1;
    if (amount == 1) {
      // Revert with a revert string
      revert("AssetTokenThatReverts: transferFrom is disabled");
    } else if (amount == 2) {
      // Revert with a custom error
      revert ThisIsACustomError();
    } else if (amount == 3) {
      // Revert with panic divide by zero
      uint256 i = 10;
      dummy = i / (i - 10);
      return false;
    } else {
      // Revert with no message
      assembly {
        revert(0, 0)
      }
    }
  }

Happy Path Sequence Diagram

The below diagram shows how the DVP workflow looks for an example three party settlement:

In my experience, articles about Zero Knowledge Proofs (ZKPs) tend to assume you are fully on board with their use cases and quickly dive into implementation details of circuits, provers and verifiers.

I think it is worthwhile to start from the business case and work the other way. This way we can learn what use cases there really are.

Imagine you are pitching a carbon-emissions product to a large company. The company wants to prove its emissions are below some threshold. Regulators, investors and customers want confidence in the reported figure. At the same time, the company does not want to expose sensitive internal data such as fleet sizes, routes, fuel usage, warehouse activity, supplier relationships, or anything else that reveals too much about how the business actually operates.

At first glance, ZKP looks perfect for this. You can pitch it in one neat sentence: “we can prove your emissions number is correct without revealing the underlying business data”.

This sounds super! It sounds privacy-preserving, technically sophisticated, exactly the sort of thing people want modern cryptography to do. The company keeps its secrets, outsiders get assurance, maths gets verified and everyone goes home happy.

Except that, if we look carefully, the interesting question was never really whether the maths was done correctly. The interesting question was where the input data came from, and why anyone should trust it.

That is the trust boundary, and that is where, in my view, some ZKP business cases start to wobble.

The carbon-emissions story

Let’s make the example more concrete.

Suppose a company claims it operated 5 trucks over some reporting period. From that, together with whatever other private operational inputs it uses, it calculates total emissions are 100 tons. It then produces a zero knowledge proof showing that this figure really does follow from the underlying calculation.

That sounds impressive, and in one narrow sense it is. The proof verifies, the output is consistent with the supplied input and the report gets a nice cryptographic sheen around it.

But now imagine the truth is that the company actually operated 6 trucks, not 5, but wilfully or accidentally entered 5 trucks into the emmissions calculation.

The ZKP has not proved that the company really operated 5 trucks. It has only proved that if the input was 5 trucks, then 100 tons is the correct result of the calculation. That is a much weaker statement than people might think they are buying.

In other words, the proof may be perfectly valid while the business claim is still false. If the trust problem lives upstream in the raw data, then the ZKP has not removed that trust. It has just wrapped the output in something that looks much more authoritative.

Now, because it can be fun to get AI to generate images of complex situations, let’s look at it pictorially:

This use case is useful as a thought experiment, because it exposes the trust boundary very clearly. The proof is not fake, the maths is not wrong, the problem is that one thing people care about is whether the hidden input reflects reality. The ZKP on its own does not answer that.

Why this pitch still sounds so compelling

Companies often do want to prove something about their operations without revealing all the operational detail underneath. A logistics firm may not want to reveal route-level data. A manufacturer may not want to expose supplier-level information. A trading firm may not want to show position-level detail. None of that is unreasonable.

The mistake is assuming that ZKP solves the separate problem of whether the hidden data is true in the first place, because it does not.

What the proof is actually proving

This is the stage where it helps to get slightly more technical.

A ZKP lets one party prove that a statement is true without revealing the private data that makes it true. In practice, we can think of four actors here, highlighted in bold: a ZKP allows us to prove that some input data X, when passed through some computation Y, produces some result Z, without necessarily revealing X itself ¹.

So in the carbon-emissions example:

• X is the private operational data, such as truck counts and fuel usage.
• Y is the carbon-emissions calculation, perhaps some ISO standard.
• Z is the reported output, such as 100 tons.
• the ZKP shows that Y(X) = Z without revealing X.

The ZKP proves that the output was correctly computed from the supplied input, but it does not prove that X is true in the real world.

I find it helpful to compare direct verification with a ZKP:

There is one more subtlety here. Zero knowledge is about what the verifier learns. Whether that verification is also fast depends on the proving system being used ². In many real-world systems, especially blockchain ones, fast verification is a major part of the appeal.

Still, whether verification is fast or private or elegant does not change the central point. If the hidden input X is self-reported and untrusted, then all we have really proved is that the claimant did the maths properly on top of their own hidden numbers. That may be better than nothing. It is not the same as proving the business claim people might have thought they were buying.

Where the trust still lives

Once you see the carbon example in those terms, the broader point becomes fairly simple. If the raw inputs are self-reported and opaque, then the ZKP mainly proves internal consistency. So where does the missing trust still live?

If the input comes from signed sensor feeds, independently audited records, regulated disclosures, tamper-resistant hardware, or some other credible attestation layer, then the story becomes much stronger. In that world, the ZKP is no longer being asked to conjure truth out of thin air. The provenance problem is being handled elsewhere, and the ZKP is doing what it is actually good at, which is preserving privacy while still proving correct computation.

So I would not say carbon emissions is always a bad fit for ZK. I would say it is a conditional fit. It only becomes compelling once the upstream data problem has already been solved by something else.

And that, in turn, creates an awkward business question. If an organisation is already prepared to trust that the hidden input data was captured honestly, then in many situations it may also be prepared to trust the rest of the calculation stack. In those cases, the incremental value of the ZKP may be smaller than a pitch deck suggests.

Where ZK is genuinely strong

Once you separate truthful input from correct computation, then stronger use cases become easier to spot.

1. Passwords, secrets and credentials

Suppose a prover wants to show they know a password, or more generally some secret, without revealing it. They can prove that they know an input which, when hashed, matches a known public value. This is exactly the kind of thing ZKPs are good at, and I wrote more about how these work in an earlier post.

The important point is not that there is literally only one possible input for a given hash output. That is not true in a strict mathematical sense ³. The point is that, under ordinary cryptographic assumptions, finding any secret that satisfies the check without actually knowing the intended one should be computationally infeasible. So the verifier gets confidence that the prover really does know the secret, without learning what it is.

This wasn’t true in our carbon emissions story, because an output of 100 tons doesn’t guarantee only 5 trucks were present in the real world.

2. EVM transactions and rollups

This is another genuinely strong use case, but for a different reason. Here, the input is typically public. Ethereum transactions are public, the state-transition rules are public and there is nothing especially secret about the underlying computation. So the value of the proof is usually not privacy.

The value is that it lets lots of people verify a large computation cheaply. Processing a large batch of EVM transactions is expensive. Re-executing them all on-chain, or forcing every verifier to do the full work, is labout intensive. A validity proof lets a prover do the heavy computation once, then gives everyone else a much cheaper way to check that the claimed state transition was valid ⁴.

That is why ZK-based rollups are such a strong use case. The proof ties the claimed output state to the batch of inputs and the execution rules, and it gives verifiers a much cheaper check than rerunning the whole computation themselves. Privacy may be absent entirely, the gain is succinct verification and scalability.

Even here, though, it is worth staying precise. A validity proof shows that the computation was correct. It does not, by itself, solve every other problem in the system. If the relevant state data is withheld, users may still have a data-availability problem even though the proof itself is valid ⁵. Again, the trust has to live somewhere.

What ZKPs actually solve

A ZKP can remove the need to reveal private input data. A ZKP can remove the need for every verifier to rerun an expensive computation. A ZKP can preserve privacy while still giving confidence in a derived claim. What it cannot do, on its own, is conjure trustworthy real-world input data out of thin air.

This distinction matters because it separates three different kinds of claim:

• Cryptographic claims. “I know a secret that satisfies this relation”.
• Computation claims. “This output really does follow from these public inputs under these rules”.
• Real-world claims. “These hidden inputs accurately describe reality”.

ZK is excellent at the first two. It is not, on its own, a solution to the third.

Footnotes

It is counter-intuitive that making a storage field larger than it needs to be can sometimes save you not only gas at runtime, but also reduce the contract deployment bytesize, but it’s true! In this post we’re going to demonstrate why this can be the case and look at the tools you can use to prove it.

Storage Slot Packing Recap

It’s pretty standard stuff to pack fields sensibly into storage slots, but this is essential background to the sections that follow. Therefore, we’re going to do a quick recap of storage slot packing in this section, and review some different tooling you can use to review opcodes and measure gas. You can skip this section if you’re already up to speed and go straight to Packing A Spare Field.

EVM Persistent Storage

EVM persistent storage is read and written in words, where each word is 32 bytes. Each word is assigned a single storage slot. Each slot can contain one or more fields. When a slot is touched it is considered “warm” for that transaction, which reduces gas fees for all interactions with all the fields in that slot.

When we get down to the opcode level, we’re going to be looking for opcodes SSTORE to write data and SLOAD to read data. The SSTORE opcode in particular is very gas intensive, which is fair enough because we’re writing data to every node in the underlying network. When you first write non-zero data to a field you’re looking at 22100 gas to pay for it.

Let’s take a very simple example contract, one that only has storage fields:

contract Storage1 {
    address owner_20;
    uint240 large_30;
    uint96 small_12;
    uint8 tiny_01;
    bool flag_01;
}

The field names include the length of the field in bytes as a postfix. This is just for our convenience, it lets us quickly see sizes in a common unit of measure. Notice that the boolean of two possible values takes up a whole byte, but that’s just the way it is.

We can see how storage is organised like this:

$ forge inspect Storage1 storageLayout
╭----------+---------+------+--------+-------+--------------------------╮
| Name     | Type    | Slot | Offset | Bytes | Contract                 |
+=======================================================================+
| owner_20 | address | 0    | 0      | 20    | src/Storage.sol:Storage1 |
|----------+---------+------+--------+-------+--------------------------|
| large_30 | uint240 | 1    | 0      | 30    | src/Storage.sol:Storage1 |
|----------+---------+------+--------+-------+--------------------------|
| small_12 | uint96  | 2    | 0      | 12    | src/Storage.sol:Storage1 |
|----------+---------+------+--------+-------+--------------------------|
| tiny_01  | uint8   | 2    | 12     | 1     | src/Storage.sol:Storage1 |
|----------+---------+------+--------+-------+--------------------------|
| flag_01  | bool    | 2    | 13     | 1     | src/Storage.sol:Storage1 |
╰----------+---------+------+--------+-------+--------------------------╯

The compiler respects the order in which we declared the variables in our source code, and tries to fit them into a linear series of 32-byte slots. The above shows our contract uses 3 storage slots. The first (slot[0]) contains the address, the second (slot[1]) contains the large integer field, and the remaining fields are all packed into the third slot (slot[2]).

We have some wasted space, though. For example, we can see slot[0] just contains the 20 bytes of an address, which means 12 bytes are left empty in that slot.

Reordering Fields

We can save a whole slot by re-ordering our variables. Let’s see what happens if we swap over large_30 and small_12:

contract Storage2 {
    address owner_20;
    uint96 small_12;
    uint240 large_30;
    uint8 tiny_01;
    bool flag_01;
}

$ forge inspect Storage2 storageLayout
╭----------+---------+------+--------+-------+--------------------------╮
| Name     | Type    | Slot | Offset | Bytes | Contract                 |
+=======================================================================+
| owner_20 | address | 0    | 0      | 20    | src/Storage.sol:Storage2 |
|----------+---------+------+--------+-------+--------------------------|
| small_12 | uint96  | 0    | 20     | 12    | src/Storage.sol:Storage2 |
|----------+---------+------+--------+-------+--------------------------|
| large_30 | uint240 | 1    | 0      | 30    | src/Storage.sol:Storage2 |
|----------+---------+------+--------+-------+--------------------------|
| tiny_01  | uint8   | 1    | 30     | 1     | src/Storage.sol:Storage2 |
|----------+---------+------+--------+----------------------------------|
| flag_01  | bool    | 1    | 31     | 1     | src/Storage.sol:Storage2 |
╰----------+---------+------+--------+-------+--------------------------╯

Awesome, now we’ve neatly filled each slot with 32 bytes. As a result, we’ve saved ourselves a whole slot! Why is this good? Well, it’s going to save us gas, let’s see how much.

Measuring Gas Usage for Storage

To measure gas usage for storage, we’re going to have to enhance our contracts a bit, because at present they’ve got a bunch of fields with the default internal visibility and no way to update them. So we can’t read or write to storage the way the contracts are just now. Lets fix that:

contract Storage1 {
    address public owner_20;
    uint240 public large_30;
    uint96 public small_12;
    uint8 public tiny_01;
    bool public flag_01;

    function setAllFields() external {
        owner_20 = msg.sender;
        large_30 = 1;
        small_12 = 2;
        tiny_01 = 3;
        flag_01 = true;
    }
}

contract Storage2 {
    address public owner_20;
    uint96 public small_12;
    uint240 public large_30;
    uint8 public tiny_01;
    bool public flag_01;

    function setAllFields() external {
        owner_20 = msg.sender;
        large_30 = 1;
        small_12 = 2;
        tiny_01 = 3;
        flag_01 = true;
    }
}

You can see from above we’ve made the fields public so that getter functions are automatically generated. We’ve also added a function to set all the fields to a non-zero value. We’re going to measure the gas usage of calling the function that writes all 5 fields at once. We’re going to do this in three different ways and compare the results.

Method 1 - Forge Test Gas Report

Ok let’s throw in a simple test and then we’ll run it with gas reporting enabled:

contract Storage1And2Test is Test {
    Storage1 public storageContract1;
    Storage2 public storageContract2;

    function setUp() public {
        storageContract1 = new Storage1();
        storageContract2 = new Storage2();
    }

    function testStorage1SetAllFields() public {
        storageContract1.setAllFields();
    }

    function testStorage2SetAllFields() public {
        storageContract2.setAllFields();
    }
}

And then the test output with gas reporting looks like this:

$ forge test --mt Storage1 --gas-report
...
╭--------------------------+-----------------+-------+--------+-------+---------╮
| src/Storage.sol:Storage1 |                 |       |        |       |         |
+===============================================================================+
| Deployment Cost          | Deployment Size |       |        |       |         |
|--------------------------+-----------------+-------+--------+-------+---------|
| 147163                   | 461             |       |        |       |         |
|--------------------------+-----------------+-------+--------+-------+---------|
| Function Name            | Min             | Avg   | Median | Max   | # Calls |
|--------------------------+-----------------+-------+--------+-------+---------|
| setAllFields             | 87681           | 87681 | 87681  | 87681 | 1       |
╰--------------------------+-----------------+-------+--------+-------+---------╯

The above shows us that Storage1 has a deploy bytesize of 461 and function setAllFields() used 87681 gas.

Method 2 - Use EVM Codes Site

The awesome EVM Codes site easily lets us see down to the opcode level and see total gas for a function call. First let’s get the bytecode for our first contract:

$ forge inspect Storage1 deployedBytecode
0x6080806040526004361015610012575f80fd5b5f3560e01c908163261cec961461015b5750806326e1ecf214610138578063ac56bff114610113578063b2b9b1ea146100eb578063c9544acc1461008d5763e3bdb95a1461005e575f80fd5b34610089575f3660031901126100895760206bffffffffffffffffffffffff60025416604051908152f35b5f80fd5b34610089575f366003190112610089575f8054336001600160a01b0319909116179055600180546001600160f01b03191681179055600280546dffffffffffffffffffffffffffff19166d0103000000000000000000000002179055005b34610089575f366003190112610089576001546040516001600160f01b039091168152602090f35b34610089575f36600319011261008957602060ff60025460681c166040519015158152f35b34610089575f36600319011261008957602060ff60025460601c16604051908152f35b34610089575f366003190112610089575f546001600160a01b03168152602090f3fea264697066735822122051e1c6c214049c5fc2b44b30f22705bfc9c1bc7aba1ead8adc9860b50300e35c64736f6c634300081e0033

We also need the data for the function call:

$ cast calldata "setAllFields()" ""
0xc9544acc

Armed with the bytecode and calldata, we go to EVM Codes playground and paste both of these items in and click “run”. We then get the opcode list for the Storage1 contract:

We clicked “run”, but notice how the site doesn’t execute the whole transaction. It just brings up the opcode list and allows us to then step through the opcodes one at a time. To complete execution of the transaction and see the gas consumed we have to click “continue execution”:

Finally, we can see the gas used is 87681:

While we’re here, we can dig into the opcodes a bit further. If you select all the opcodes and paste them into a text editor, and then count how many SSTORE opcodes there are, how many do you get? You should get 3. That’s because we write to 3 storage slots. Each slot written costs one SSTORE operation.

Bonus Method: Note that we could get a similar result of seeing the opcodes using the decompiler from the dedaub site, just as we did in this earlier post.

Method 3 - Forge Test With Verbose Logs

We can also see gas consumed from the most verbose logs of a forge test run.

$ forge test --mt Storage1 -vvvvv
...
Traces:
...
  [71917] Storage1And2Test::testStorage1SetAllFields()
    ├─ [66617] Storage1::setAllFields()
    │   ├─  storage changes:
    │   │   @ 2: 0 → 0x0000000000000000000000000000000000000103000000000000000000000002
    │   │   @ 0: 0 → 0x0000000000000000000000007fa9385be102ac3eac297483dd6233d62b3e1496
    │   │   @ 1: 0 → 1
    │   └─ ← [Stop]
    └─ ← [Stop]

We can see from above that the function setAllFields() cost 66617 gas, and we can see under the section storage changes: that there were three storage slots written to (numbered @ 2, @ 0, @ 1 in the log).

Comparing Measurements

We can repeat the above measurement methods 1 to 3 for the contract Storage2, and collate the results like so:

We can see that the Storage2 contract was over 20000 gas cheaper, all because we saved writing to a storage slot. It also meant a small contract deploy size, since we needed fewer opcodes (one less SSTORE).

The figures for method 3 do stand out, though. Why do the gas usage numbers for forge test ... -vvvvv (method 3) disagree with the other methods? The answer is that methods 1 and 2 include the overhead costs of a full transaction, as it were being called from an external client. Method 3 gives the cost only of the function call, without the transaction “wrapper”. The overhead of the transaction is a flat 21000 gas plus 64 gas for the function selector (16 gas * 4 bytes). It would be higher if we’d passed more calldata.

Packing A Spare Field

Now let’s see what happens when we need to pack in one more field. Let’s say we have another uint8 that needs added. Since our storage is already perfectly packed into 32-byte words, we will just plonk it on the end:

contract Storage3 {
    address owner_20;
    uint96 small_12;
    uint240 large_30;
    uint8 tiny_01;
    bool flag_01;
    uint8 public anotherTiny_01;  // <-- the new field
}

We’ve also removed the other getters, and removed the setter function to simplify. Let’s compare this contract’s deploy size and gas usage with another where we make the new field a uint256 (even though our business requirements only need a uint8):

contract Storage4 {
    address owner_20;
    uint96 small_12;
    uint240 large_30;
    uint8 tiny_01;
    bool flag_01;
    uint256 public anotherTiny_01;  // <-- the new field, made larger
}

Measuring Gas Usage

Now let’s add a super simple test to just read the field in each case, and see which getter function for the new field anotherTiny_01 consumes the least gas.

contract Storage3And4Test is Test {
    Storage3 public storageContract3;
    Storage4 public storageContract4;

    function setUp() public {
        storageContract3 = new Storage3();
        storageContract4 = new Storage4();
    }

    function testStorage3And4() public view {
        assertEq(storageContract3.anotherTiny_01(), 0);
        assertEq(storageContract4.anotherTiny_01(), 0);
    }    
}

$ forge test --mt Storage3And4 --gas-report
...
╭---------------------------+-----------------+------+--------+------+---------╮
| src/Storage.sol:Storage3  |                 |      |        |      |         |
+==============================================================================+
| Deployment Cost           | Deployment Size |      |        |      |         |
|---------------------------+-----------------+------+--------+------+---------|
| 79371                     | 144             |      |        |      |         |
|---------------------------+-----------------+------+--------+------+---------|
| Function Name             | Min             | Avg  | Median | Max  | # Calls |
|---------------------------+-----------------+------+--------+------+---------|
| anotherTiny_01            | 2248            | 2248 | 2248   | 2248 | 1       |
╰---------------------------+-----------------+------+--------+------+---------╯

╭---------------------------+-----------------+------+--------+------+---------╮
| src/Storage.sol:Storage4  |                 |      |        |      |         |
+==============================================================================+
| Deployment Cost           | Deployment Size |      |        |      |         |
|---------------------------+-----------------+------+--------+------+---------|
| 78723                     | 141             |      |        |      |         |
|---------------------------+-----------------+------+--------+------+---------|
| Function Name             | Min             | Avg  | Median | Max  | # Calls |
|---------------------------+-----------------+------+--------+------+---------|
| anotherTiny_01            | 2242            | 2242 | 2242   | 2242 | 1       |
╰---------------------------+-----------------+------+--------+------+---------╯

The above shows the surprising result, that not only is the uint256 storage variable giving us a smaller contract deployment size (141 versus 144 bytes), it is also consuming less gas when we read it (2242 versus 2248 gas)!

How can this be? How can making a field larger be more efficient? To answer that, we need to look into what opcodes are being used.

Opcode Analysis

We get the deployed bytecode for contract Storage3 like this:

$ forge inspect Storage3 deployedBytecode
0x60808060405260043610156011575f80fd5b5f3560e01c63801147b7146023575f80fd5b34603e575f366003190112603e5760209060ff600254168152f35b5f80fdfea2646970667358221220450ff733407af87c2e1ce4d218c1c4712e7e982f7db6753aeb65e5d71f90a50664736f6c634300081e0033

We get the information we need for the calldata field like this:

$ cast calldata "anotherTiny_01()" ""
0x801147b7

And again we can use the EVM Codes site and paste in the deployed bytecode and the calldata of 0x801147b7 to see the opcodes. These are the same steps we took in this earlier section to look at gas usage. We then repeat above steps for contract Storage4 and we can compare how the source opcodes look.

The reason for the difference lies near the end of the contract opcode list. To orientate ourselves in the code, we’re looking for an SLOAD opcode (which is us reading a value from storage) near to a RETURN opcode (which is the function returning the value). Let’s see both listings, with annotations, then I’ll explain more:

Opcode List Extract for Storage3

[32] PUSH1 20   <-- Prepare offset in stack, we'll return this later
[34] SWAP1      <-- Arrange stack
[35] PUSH1 ff   <-- [EXTRA] Prepare a mask of 1 byte
[37] PUSH1 02   <-- Push 2 to stack (representing storage slot #2)
[39] SLOAD      <-- Load storage slot #2 (the field anotherTiny_01)
[3a] AND        <-- [EXTRA] Combine mask with SLOADed data, so we read 1st byte
[3b] DUP2       <-- Duplicate the offset because MSTORE will consume it
[3c] MSTORE     <-- Copy to memory 
[3d] RETURN     <-- Return memory as function return value

Opcode List Extract for Storage4

[32] PUSH1 20   <-- Prepare offset in stack, we'll return this later
[34] SWAP1      <-- Arrange stack
[35] PUSH1 02   <-- Push 2 (representing storage slot #2) to stack
[37] SLOAD      <-- Load storage slot #2 (the field anotherTiny_01)
[38] DUP2       <-- Duplicate the offset because MSTORE will consume it
[39] MSTORE     <-- Copy to memory 
[3a] RETURN     <-- Return memory as function return value

What the above shows is that the Storage3 contract has two extra opcodes, annotated with [EXTRA]. Remember that slots are read in whole 32-byte words, even if you touch only a small part of that word. What these additional opcodes are doing is masking the 32-bytes returned by the SLOAD such that only the 1 byte of our field anotherTiny_01 is allowed to “shine through”. Since the ABI returns a 32-byte word anyway, this overhead of chopping out just the 1 byte we use, is using more gas than we need.

In contract Storage4 we’re saving two opcode operations, because we just read out and return the whole 32-byte word from storage. This is why we save deployed bytesize and gas!

There is a small downside, though. If we make our field uint256 instead of uint8 we’re losing some degree of type safety, because perhaps we’d like the EVM to revert if our value gets too big.

Nevertheless, it’s an interesting micro-optimisation and sheds some light on EVM internals and the tools used to examine it.

You may think that the function names you choose in your Solidity contracts don’t matter when it comes to runtime gas consumption, and to an extent that is true. However, there are edge cases where function naming does affect runtime gas consumption! In this post we’re going to demonstrate this, as well as the tooling you can use to prove it. We’re going to use Foundry tools, but you don’t need those to follow along.

Function Selectors

It is true that the length of the function name makes no difference to how the contract is deployed or how it behaves on-chain, because the function name doesn’t go on-chain at all. When a contract is compiled, a function selector is calculated for each function, and that is what goes into the bytecode and goes on-chain. The function selector is the first 4-bytes of the Keccak-256 hash of the canonical signature of the function. For example:

So from above, it is clear that it doesn’t matter if our function name is 10 characters long or 50 characters long, because what gets deployed in the compiled bytecode is a function selector that is always 4 bytes long. All well and good, but why then might function names matter? To answer that we need to get to a lower level, and examine what happens at the opcode level.

The Jump Table

When your contract is compiled, part of the resulting code is a jump table. The jump table is used to check what function is being asked for from the transaction data field, and jumps to the correct memory location for that function body. The code that does this is referred to as a jump table, but it isn’t a table in the database sense, it is just more bytecode.

Let’s look at a worked example to make this clearer. First let’s go with some standard optimisation, so in foundry.toml we have:

optimizer = true
optimizer_runs = 200

Next, let’s consider the below Solidity contract:

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

contract JumpTable {
    uint256 private _number;

    function setNumberA(uint256 number) external {
        _number = number;
    }

    function setNumberB(uint256 number) external {
        _number = number;
    }

    function setNumberC(uint256 number) external {
        _number = number;
    }

    function setNumberD(uint256 number) external {
        _number = number;
    }
}

The above shows we have 4 identical functions. We can get the function selectors like this:

$ forge inspect JumpTable methodIdentifiers
╭---------------------+------------╮
| Method              | Identifier |
+==================================+
| setNumberA(uint256) | 4c67b768   |
|---------------------+------------|
| setNumberB(uint256) | 6e19ab5d   |
|---------------------+------------|
| setNumberC(uint256) | 1b877640   |
|---------------------+------------|
| setNumberD(uint256) | fe13be0d   |
╰---------------------+------------╯

If we wanted to call function setNumberC(2) we could work out what calldata to use like this:

$ cast calldata "setNumberC(uint256)" "2"
0x1b8776400000000000000000000000000000000000000000000000000000000000000002

The first 4 bytes of the above result is us telling the EVM what function we want to call. We are passing the function selector 0x1b877640. That selector id matches the value from the table earlier, when we did forge inspect. The other 32 bytes of the calldata contain the parameter value of 2, padded out to fill one 32-byte word.

When the EVM receives this calldata, it checks all the function names to see which one, if any, it should execute. It is the equivalent of doing a bunch of if statements to see if the contract has the function being asked for. The code to do this is called the jump table. Let’s examine the compiled code more closely so we can see how the jump table works.

Examining Opcodes for The Jump Table

We get the deployed bytecode like this:

$ forge inspect JumpTable deployedBytecode
0x608060405260043610156010575f80fd5b5f3560e01c80631b8776401460405780634c67b7681460405780636e19ab5d1460405763fe13be0d146040575f80fd5b3460565760203660031901126056576004355f55005b5f80fdfea26469706673582212204d9d17a05e72cb1931b3eb546aa7112b1616522ba8d31b419d8482dfe4e3926a64736f6c634300081e0033

We can get the opcodes from that in a few ways. The EVM Codes Playground is great, but we’ll try dedaub this time. Go to the dedaub site, click “Decompiler” on the top menu and paste in the bytecode we just got:

Then click the “decompile” button and wait a short while to see the output. Scroll down a little until you can see the CALLDATALOAD opcode:

The above shows the jump table checking the call data against each of the function selectors we derived earlier. We don’t need to go through it line by line, but you can get the flavour of it: the PUSH4 opcodes are pushing the known function selectors onto the stack and if we get a match with the function our calldata asked for, then we do a JUMP to the function implementation (the JUMPI opcodes jump if a condition is met).

Now here is the critical point: we can see from above that if the function we asked for was the first hit in the jump table, we’re going to have to do less work than if it were the final hit in that jump table.

Less work means less gas! The functions are listed in the jump table ordered not by their long function names, but by their function selectors. You can see the first function selector checked in the jump table is 0x1b877640 which is for function setNumberC(). This means that function C should cost less gas than all the others, even though all functions do the same thing! Let’s prove it.

Proving Function C is the Cheapest

Let’s write ourselves a super simple test, then we can use the forge gas report to see which function is cheapest.

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

import "forge-std/Test.sol";
import "../../src/internals/JumpTable.sol";

contract JumpTableTest is Test {
    JumpTable public jumpTableContract;

    function setUp() public {
        jumpTableContract = new JumpTable();
    }

    function testJumpTableA() public {
        jumpTableContract.setNumberA(2);
    }

    function testJumpTableB() public {
        jumpTableContract.setNumberB(2);
    }

    function testJumpTableC() public {
        jumpTableContract.setNumberC(2);
    }

    function testJumpTableD() public {
        jumpTableContract.setNumberD(2);
    }
}

We can run the test like this:

$ forge test --mt JumpTable --gas-report
...
╭----------------+-----------+-------+--------+-------+---------╮
| Function Name  | Min       | Avg   | Median | Max   | # Calls |
|----------------+-----------+-------+--------+-------+---------|
| setNumberA     | 43456     | 43456 | 43456  | 43456 | 1       |
|----------------+-----------+-------+--------+-------+---------|
| setNumberB     | 43478     | 43478 | 43478  | 43478 | 1       |
|----------------+-----------+-------+--------+-------+---------|
| setNumberC     | 43434     | 43434 | 43434  | 43434 | 1       |
|----------------+-----------+-------+--------+-------+---------|
| setNumberD     | 43497     | 43497 | 43497  | 43497 | 1       |
╰----------------+-----------+-------+--------+-------+---------╯

We can see Function C is always cheaper! In fact cheaper by 63 gas compared with the most expensive, function B. The order of gas consumption from cheapest to most expensive is: C, A, B, D. This matches our function selectors if we order them by selector id:

╭---------------------+------------╮
| Method              | (Sorted)   |
+==================================+
| setNumberC(uint256) | 1b877640   |
|---------------------+------------|
| setNumberA(uint256) | 4c67b768   |
|---------------------+------------|
| setNumberB(uint256) | 6e19ab5d   |
|---------------------+------------|
| setNumberD(uint256) | fe13be0d   |
╰---------------------+------------╯

So there you have it. If you know you have a function that will be called significantly more than others, you can save a tiny bit of gas by carefully picking a function name that hashes to give a function selector that sorts before the other function selectors.

Caveats

Although it is fun to step through opcodes and review what the compiler produces, there are some pretty important caveats to this micro-optimisation:

• Once you get above 8 functions, the compiler optimises, and switches to producing code that does a binary search to decide which jump table item was hit. So in practice this micro-optimisation isn’t going to be very common.
• The gas saving was miniscule, 60 gas out of 23500 or 0.2% in this toy example. In extreme usage cases this might matter, but in most cases it won’t matter.
• The cognitive load of obfuscating your own function names by choosing a name you didn’t want to, may outweigh the benefit. I know it’s not really obfuscation, as you could postfix your chosen function name with something small, but the principle remains, that this adds to the visual complexity.

After wading through tons (and tons) of documentation about AMMs and bonding curves I found that some concepts, if I’d understood them at the start, would have made learning so much easier. I’ve collected these observations here, in the hope that it helps others understand how bonding curves work. But before we dive into bonding curves themselves, we need to understand some other terminology and background.

Order Books

When people want to trade something, a common pattern is to maintain an order book. An order book lets buyers record what they want to buy (e.g. Alice wants to buy 100 apples and is prepared to accept 90 pears), and lets sellers record what they want to sell (e.g. Bob wants to sell 90 pears and wants 100 apples). A third party can then use that order book to match buyers with sellers and help perform the asset transfers. This works well so long as you have active lists of buyers and sellers and you can find matches.

Automated Market Makers

An alternative to this order book matching idea has been discussed since the early 2000s. It is the Automated Market Maker or AMM. The idea is that a “pool” is created that contains all the assets that people might want to trade “pre-loaded”. So in our example, we could create an “apples & pears” pool and load it with hundreds of apples and pears. That way, a buyer or seller of either fruit would be able to do their trade directly with this pool, at any time, without having to wait to find a matching order.

The people who fill the pool with the assets are called Liquidity Providers or LPs. They generally deposit lots of both the assets that buyers and sellers want to trade between. LPs can earn a return by taking a percentage of each trade done in the pool. Various pool projects also offer other incentives like bonuses to attract LPs.

Bonding Curves

The idea of AMMs came to the fore again with early blockchain work, Uniswap being one of the early implementations. A thorny question for AMMs was “how can we fairly price the assets in this pool?” and that is answered by using a bonding curve. It is basically a formula, the purpose being to help allow the AMM pool to offer fair prices to buyers and sellers, regardless of their desired trade size and the pool state.

Some Insights

In the below, we’re going to imagine we’re dealing with an AMM pool that can be used to swap back and forth between gold coins and silver coins. These coins of course could represent any on-chain tokens, but for the analogies to work well it’s sometimes helpful to imagine physical coins that we can stack. To make the diagrams easier, we’re going to pretend the silver coins are really high quality and the gold ones are lesser quality, such that initially the coins should trade at 1:1.

1. A Bonding Curve is like a Maze Panel

Imagine you’re in a playground and you see one of those panel things that lets you slide a handle along a curve. The handle is fixed to the rails so can only move where the curve allows it to. It turns out these are called “maze panels” and they can help us form a really useful analogy to a bonding curve.

Imagine the maze panel represents our pool. Wherever the yellow handle is, marks the current state of the pool. The pool state is simply an amount of gold and silver coins. Only the states along the maze panel’s engineered curve are allowed. The pool can’t be in any other state any more than you can move the yellow handle anywhere apart from that pre-defined curve. That maze panel curve is our bonding curve.

How exactly does the yellow handle represent state? The yellow handle gives us a single (x, y) coordinate, where x represents the amount of gold coins, y the amount of silver coins. We can imagine stacks of coins, representing the tokens in the pool, neatly arranged to run from the edges of the maze panel (the x and y axes) to the yellow handle (the current pool state). We can clearly see how many tokens there are in the pool for its given state:

Or we can draw on some axes and show the same amounts of coins like this:

We can also imagine, if the yellow handle were moved to the left, so that it slid along the curve and upwards, then that new pool state would have fewer gold coins and more silver coins. The bonding curve is never perfectly horizontal or vertical, it’s always got a slight slope. It hard to get that visually accurate in the maze panel photos, but we can imagine.

That leads us to the question, then, how does the pool change state? What can cause the handle to move? The answer to that, lies in how we interact with the pool. We’ve got two main choices:

• When someone trades with the pool (that is, they do a swap) then that yellow handle slides a bit to the left or right, according to which direction the swap was. When someone does a swap, the put in some coins and remove some coins. This causes the heights of the stacks of coins to change and so moves the yellow handle. The size of the trade (the quantities of each coin) affects how far the handle moves. We’re going to look at how trades work in more detail in the next section: ‘You Affect the Price You Get’.
• When someone adds or removes liquidity in the pool, something special happens to the curve shape on our maze panel. We discuss this more in the section ‘The Invariant is Not Invariant’.

2. You Affect the Price You Get

Ok, so now we’re going to look in detail at how a trade (a swap) affects the pool. We know already that trades are going to “move the yellow handle” in our maze panel analogy, but by how far?

Let’s imagine our pool has 100 gold and 100 silver coins so it starts off with an initial pool state of (100, 100). Alice comes along and says “I want to buy some silver, here is 30 gold what will I get back?”. The AMM pool can do a calculation to answer this. The bonding curve is fixed in place, like our maze panel slot, but we can slide along it by +30 coins along the gold (x) axis and see what silver (y) coordinate we will get as a result:

The diagram shows that if we move +30 along the x-axis (dx) we will end up with a y-coordinate movement of 100 - 72 which is -28 (dy). So Alice will get back 28 silver coins.

This is the heart of how AMMs work. Alice, as the trader, can control how big a trade she asks for. If she were to say she wants to spend 300 gold coins, we’d end up sliding along the x-axis for a long way, but we’d only move a relatively short distance on the y-axis. So Alice would get a really bad deal on a gigantic trade that adds lots of gold.

Alice’s better strategy would be to do multiple small trades, and hope other traders take the opposite swap direction in between. The closer the yellow handle is to the centre of the chart, the better the price is for everyone.

If Alice did decide to spend 300 gold on some silver, regardless of the fact she’d get a bad deal, then what would happen? The yellow handle would move way to the right of the curve, and then other traders are incentivised to move it back to the centre again, to go the opposite way, because the pool would be offering an awesome deal on purchases of gold. Alice would have made the pool “gold heavy” and that means using a small amount of silver to buy gold would get us a great deal. Our pool’s customers are incentivised to bring the pool back to balance again.

3. The Invariant is Not Invariant

As already mentioned, Liquidity Providers (LPs) pour in pairs of tokens to AMM pools. In our sample pool of gold and silver coins, we expect it to start off balanced and to trade at around 1:1 when the pool starts up.

What is interesting, though, is what happens to our maze panel curve when an LP adds pairs of tokens to an AMM pool after that initial deployment. As mentioned, a bonding curve is just a formula. For example, Uniswap use the famous constant product formula x.y = k which says that the quantity of gold coins times the quantity of silver coins must always equal the constant k. This value k is often called “the invariant” and the formula itself is called “the invariant formula”.

But here’s the insight, the invariant k is not invariant when an LP adds or removes liquidity. When an LP adds more liquidity the value k increases, because we have more gold coins and silver coins to go around. If an LP removes liquidity we have less to go around, and k has to decrease. The invariant k is only really invariant during swaps. Note however, that the bonding curve formula remains the same (x.y = k in this example), it’s just that one of the parameters is changing.

Here’s a diagram of how the curve (aka our maze panel slot) changes as more liquidity is added:

We can see the curve “flattens” as more liquidity is added. Crucially, a flatter curve means a better price for both buyers and sellers, so a pool with a lot of liquidity is a good thing. The more coins LPs put in, the better it is for everyone trading. Remember that during a trade, it doesn’t matter where in the xy plane we are, what matters is the slope of the curve because it is the slope of the curve that determines the prices.

4. AMM Projects Determine Bonding Curve Shape

The bonding curve shape, aka the maze panel cutout shape, also varies by AMM project. Different projects offer different curve formulas and different parameters you can tweak to alter the shape to suit your use case.

For example, tokens that we know should trade at very close to 1:1 always, like pairs of USD stablecoins, benefit from having a “flatter” bonding curve in the middle. This is shown in the diagram below by the yellow line, from the Curve project’s Stableswap bonding curve.

5. Curve StableswapNG Parameters

Different AMM projects allow you to tweak their curve in different ways. For example, Curve’s StableswapNG pool offers several parameters to tweak their curve to suit your preferences. The parameters are shown below, along with samples of what some existing large pools use there:

• A = Amplification Coefficient. Range 0 to 5000. Larger values mean flatter curve centre, so large swaps move price less there.
• Off peg multiplier. Range 0 to 12.5. Larger values mean swaps that unbalance an unbalanced pool further are hit with higher fees.
• Moving average time. Range 60 to 3600 seconds. Larger values mean point moves more slowly along the bonding curve, like its movement is “dampened” across time.

That’s it for now! I’ve collected material for a “bonding curves part 2”, where we can extend our understanding to concentrated liquidity, oracle integration and tri-pools but that’s for another day.

Address poisoning is when an attacker tries to insert a malicious address into your wallet’s “recently used addresses” list. They do this in the hope that when you next make a transaction, you will send it to the malicious address by accident. At the heart of this is a malicious address that looks a bit like a known good address, in the sense that it starts and ends with the same hex. This is the malicious address, the “poisoned address”.

The attack can involve sending you tokens from a malicious address. A more advanced variant of the attack involves spoofing the sending of tokens to a malicious address, such that they look like they originated from your address. We will look at both types, and explore a real world example.

Crafting Malicious Addresses

Let’s say you interact quite often with a known good address:

Address = 0x0040904745013aDE49C4589eC52b998CA6F09000
Key = 1bf2e5e2f7ac05c6e071ea1b6f2879e8f4c97473b7039dfcfa757b53e62f8a69

When checking it, you glance at the first 3 chars because you know it starts with “004” and you glance at the end which is “9 and some zeroes”.

The attacker wants to create a malicious address that looks a bit like the one above. There is a simple address generator available online https://vanity-eth.tk/. You can see how easy it is to generate an address with characters of your choice. In under 2 minutes we can produce this malicious address:

Address = 0x0044209858ca9a86FaA9E03F5520F8725449a900
Key = 6d0110d772bc2217946adea8dca0d58d8a6c76949424f11e019e79df30bc23f0

If you were in a hurry, you might glance at the above and say “yeah it starts with 004 and ends with 9 and some zeroes, we’re good”. The fact that the address was listed in your wallet’s “recently used” list further supports the idea that the address is good.

Now that we’ve got our malicious address, how does an attacker get that into our wallet’s “recently used” list?

Getting a Malicious Address into a Wallet’s “Recently Used” List

1. Recently Received From (aka Receiving Dust)

The receiving of ERC20 tokens cannot be prevented. It is of course very simple to send fake tokens, or to send miniscule amounts (“dust”) of real tokens to an address. So attackers can send something from a malicious address to your address, and these will appear in your wallet’s “recently used” or “transaction activity” list.

It depends on your wallet, but these will appear under the grouping of addresses labelled as “received from”. This is fair enough, but the attacker’s thinking goes that you are more likely to re-use their malicious address if you see it in your “recently sent to addresses” list. So the attacker’s goal is to get their malicious address into your “recently sent to” address list. But how could that be possible? Let’s find out…

2. Recently Sent To (aka Spoofing Sent Tokens)

For the attacker to pollute our “recently sent to addresses” list in our wallet, they exploit the fact that many wallets don’t care who sent a transaction, instead they listen for events. For example, imagine a legitimate ERC-20 token transfer of USDC from Alice to ourselves. When this happens, we see two things on-chain:

1. A transaction occurs on-chain. This transaction could show Transaction From Address: Alice and Transaction To Address: USDC contract. Or it could show Transaction From Address: Bob and Transaction To Address: Some other contract and that other contract makes the call to do the transfer of USDC from Alice to ourselves. The point is, it would be extremely complex to work out from just the raw transaction data (Transaction From Address, Transaction To Address and associated data) what movements of tokens are happening.
2. An ERC-20 transfer event is emitted by the USDC contract. No matter who initiated the transaction, or which contract first received the transaction, at some point the USDC contract will emit a transfer event with Transfer From Address: Alice and Transfer To Address: ourselves. If a transaction makes more than one transfer then more than one transfer event will be emitted.

From the point of view of the wallet, it wants to know what addresses it should put into the “recently sent to addresses” list. Given that 1. is super-complex and 2. is super-easy, it makes sense to rely on listening for events. This is what events are for, after all, and this is what the attacker exploits.

The attacker can deploy an evil contract that emits transfer events with any Transfer From Address and Transfer To Address they wish. Their evil contact doesn’t actually move any tokens, or send anything at all. It only emits transfer events that appear to be genuine ERC-20 events. The events emitted can have a From Address: Your Address and a To Address: The Attacker's Malicious Address. This To address is the one that the attacker hopes you will pick by accident.

If we were to look more closely at this event, we’d see that the contract that emitted the event wasn’t USDC, or any known ERC-20. It was the attacker’s evil contract. There is no official central policing of ERC-20s, so wallets can’t easily tell if a transfer event is genuine or not (although there are services that try to address this).

Real World Example

Qualifying as an Intended Target

These address poisoning attacks have a cost associated with them for the attacker. This cost may be small, depending on the chain, but they still have to pay gas and manage bulk emissions of events. So they don’t poison addresses willy-nilly, they target addresses that have recently made large, genuine, transfers.

Polygon Address Poisoning

This example is on Polygon, gas is very cheap which reduces cost for the attacker. The attacker has an “orchestration” contract that makes transfer() calls out to many malicious tokens. One such malicious token is here.

Neither contract has source code associated with it which is a red flag for a token. We can however, take the bytecode and decompile it. An excellent service for this is Dedaub, which let’s us see the decompiled “pseudo-Solidity” like this:

function transfer(address _from, address _to, uint256 _wad) public payable { 
    emit Transfer(_from, _to, _wad);
}

As you can see, they’re not transferring anything, they just emit an event that says an address did a transfer when it did not. Wallets pick up those events and interpret them as a genuine transfer.

Effects on Other Services

Poisoning doesn’t just affect wallets. It affects any service that collects transfer information, for example services that calculate tax. Address poisoning isn’t a small problem, it is now possible to buy address poisoning toolkits(!), as detailed in this Chainalysis article.

When you call a Solidity function with a dynamic argument like an array or bytes, the ABI encoder represents that argument using an offset and a length, not in-place data. This design allows multiple distinct calldata layouts to decode to the same input values, which will perform the same function execution steps, even though their raw bytes differ. This subtlety of the Solidity ABI is known as input malleability, and it has consequences for logic that relies on parsing calldata manually. This article explains in detail how this works, and the potential consequences of forgetting about it.

We will look at some examples of calldata, decode them with tools and then manually, and get a good understanding of what is going on “under the hood”.

Example Calldata

Here is an example of two distinct calldata strings that decode to produce the same function execution steps. It is not possible to decode calldata reliably without knowing the function signature. To get the function signature we need source code, the ABI, or we can rely on a service like 4byte.directory. In the below we’re going to use Foundry’s cast 4byte-decode.

Calldata A

Consider the calldata below. It is 200 bytes long (402 chars with the 0x prefix). Let’s see what Solidity function it will execute and with what parameters:

0x1cff79cd0000000000000000000000001240fa2a84dd9157a0e76b5cfe98b1d52268b26400000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064d9caed120000000000000000000000008ad159a275aee56fb2334dbb69036e9c7bacee9b00000000000000000000000044e97af4418b7a17aabd8090bea0a471a366305c0000000000000000000000000000000000000000000000000000000000000001

We can use cast to decode the above:

$ cast 4byte-decode 0x1cff79cd0000000000000000000000001240fa2a84dd9157a0e76b5cfe98b1d52268b26400000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064d9caed120000000000000000000000008ad159a275aee56fb2334dbb69036e9c7bacee9b00000000000000000000000044e97af4418b7a17aabd8090bea0a471a366305c0000000000000000000000000000000000000000000000000000000000000001
1) "execute(address,bytes)"
0x1240FA2A84dd9157a0e76B5Cfe98B1d52268B264
0xd9caed120000000000000000000000008ad159a275aee56fb2334dbb69036e9c7bacee9b00000000000000000000000044e97af4418b7a17aabd8090bea0a471a366305c0000000000000000000000000000000000000000000000000000000000000001

We can see from above that Calldata A will call a function called execute that expects an address and a bytes array. The above shows the address is 0x1240FA..64 and the bytes array is 0xd9caed..01.

Calldata B

Here is another calldata string, different from Calldata A. Although it starts and ends with the same bytes as Calldata A, this Calldata B is longer, weighing in at 266 bytes (530 chars including the 0x prefix). We will examine actual the differences later, but for now let’s see what Solidity function it will execute, and with what parameters:

0x1cff79cd0000000000000000000000001240fa2a84dd9157a0e76b5cfe98b1d52268b2640000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000064d9caed120000000000000000000000008ad159a275aee56fb2334dbb69036e9c7bacee9b00000000000000000000000044e97af4418b7a17aabd8090bea0a471a366305c0000000000000000000000000000000000000000000000000000000000000001

Again we use cast to decode this:

$ cast 4byte-decode 0x1cff79cd0000000000000000000000001240fa2a84dd9157a0e76b5cfe98b1d52268b2640000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000064d9caed120000000000000000000000008ad159a275aee56fb2334dbb69036e9c7bacee9b00000000000000000000000044e97af4418b7a17aabd8090bea0a471a366305c0000000000000000000000000000000000000000000000000000000000000001
1) "execute(address,bytes)"
0x1240FA2A84dd9157a0e76B5Cfe98B1d52268B264
0xd9caed120000000000000000000000008ad159a275aee56fb2334dbb69036e9c7bacee9b00000000000000000000000044e97af4418b7a17aabd8090bea0a471a366305c0000000000000000000000000000000000000000000000000000000000000001

The above shows that, again, we are calling a function execute. Looking more closely, we can see that we’re calling that function with the same parameters and values as we had with Calldata A. The first parameter is an address 0x1240FA..64 and the bytes array is 0xd9caed..01. The bytes array is of length 100 bytes, identical to the bytes array from Calldata A.

So, we have two different calldata strings, one of length 200 bytes (Calldata A) and one of length 266 bytes (Calldata B) and yet cast decoded them into the precise same function call and parameter values! To find out what is going on, we need to manually decode the calldata strings.

Manual Decoding

We’re now going to perform some manual decoding, which will reveal why the two different calldata strings produce the same results. There is a very thorough article that goes into ABI coding and decoding in more detail than we need for our case. It is worth a read if you’re dealing with more complex function parameters such as nested structs.

Manual Decoding of Calldata A

It is pretty easy to manually decode calldata using a text editor to rearrange the data. We can paste the raw Calldata A into a text editor and as a first pass we can hit enter a few times to chop it into logical pieces:

0x
1cff79cd
0000000000000000000000001240fa2a84dd9157a0e76b5cfe98b1d52268b264
0000000000000000000000000000000000000000000000000000000000000040
0000000000000000000000000000000000000000000000000000000000000064
d9caed120000000000000000000000008ad159a275aee56fb2334dbb69036e9c7bacee9b00000000000000000000000044e97af4418b7a17aabd8090bea0a471a366305c0000000000000000000000000000000000000000000000000000000000000001

Annotating the above, we get:

In the above, the blue fields are always present. The calldata always starts with a function selector. Most fields after that will be treated as 32-byte words (64 chars in our text editor) but not all, as we shall see. In this example the function selector is 1cff79cd which tells us the function signature is execute(address,bytes). We know this because we saw it from the cast command above or we can check it from the 4byte.directory service. The yellow fields depend on the function signature, but there is always going to be some arrangement of 32-byte words somewhere.

Given that we know the function signature is execute(address,bytes), we can press enter a couple more times to separate the function parameters more clearly:

In the above, we can see the address parameter is very simple, it is padded to 32 bytes and is stored in place. The bytes parameter is dynamic and is not stored in place like the address, and this is the heart of the malleability feature. The bytes parameter is stored in three parts: the offset, the length and the actual data:

• offset: 32-byte word containing a pointer to where the length field starts. The offset is measured in bytes, counted from the start of the calldata field, but without the selector part. This “offset start point” is shown as the blue arrow in the above diagram. In this case, the offset value is 0x40 or 64 bytes, which measured from the blue arrow takes us directly to the next field, the length field, with no gaps.
• length: 32-byte word containing the number of bytes in the bytes array. The offset points to this length field. The actual data follows immediately after this field.
• actual data: the actual data, as one long array of bytes.

This result matches what we saw above when we decoded the calldata using cast. The first parameter is an address 0x1240FA..64 and the bytes array is 0xd9caed..01, of length 100 bytes. There are no surprises here, we’re just learning how to manually decode the calldata.

Manual Decoding of Calldata B

Now we can perform the same steps again, and see what results we get when we manually decode Calldata B. We paste Calldata B into a text editor and press enter a few times:

0x
1cff79cd
0000000000000000000000001240fa2a84dd9157a0e76b5cfe98b1d52268b264
0000000000000000000000000000000000000000000000000000000000000080
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000064
d9caed120000000000000000000000008ad159a275aee56fb2334dbb69036e9c7bacee9b00000000000000000000000044e97af4418b7a17aabd8090bea0a471a366305c0000000000000000000000000000000000000000000000000000000000000001

Clearly, the above calldata is longer than the Calldata A. Annotating the above, we get:

The above diagram shows the address parameter is the same as for Calldata A. However, the bytes parameter parts are subtly different:

• offset: 32-byte word containing a pointer to where the length field starts. The offset is measured in bytes, counted from the start of the calldata field, but without the selector part. This “offset start point” is shown as the blue arrow in the above diagram. In this case the offset value is 0x80 or 128 bytes, which measured from the blue arrow takes us to the next field, the length field, but with a 64 byte gap inbetween!
• length: Identical to Calldata A.
• actual data: Identical to Calldata A.

The blue highlighted 64 bytes in the above diagram is just redundant padding. These bytes are not used in this example, and can contain any data. They are there because the offset field points “further ahead” than in the Calldata A example, and we need to fill that gap.

The effect of the above Calldata B, in terms of what the EVM will do when the calldata is executed, is identical to the result of Calldata A. The two calldata strings have the same functional intent.

Why should I care?

To summarise up to this point: we have two distinct calldata strings, Calldata A and Calldata B that produce the same functional intent, which is to call a function called execute with the same paramaters. We’ve verified this with cast and by manual decoding. We’ve learned Calldata B is a bit longer, and has some padding and unused data, but if the calldata produces the same functional effects, who cares?

The answer to that lies with functions that read raw calldata. If the execute() function reads the parameters as normal, there is not an issue:

function execute(address target, bytes calldata actionData) external {
  // If code only reads target and actionData parameters then no problem
  // ...
}

However:

• if the execute() function reads raw calldata directly…
• …and the function makes assumptions about the positioning of data within that raw calldata…
• …then there is a potential problem.

Let’s look at an example execute() function that shows this potential problem:

function execute(address target, bytes calldata actionData) external {
  // Read the 4-bytes selector at the beginning of `actionData`
  bytes4 selector;
  uint256 calldataOffset = 4 + 32 * 3; // Fixed calldata position where `actionData` begins
  assembly {
    selector := calldataload(calldataOffset)
  }
  // ...
}

The above code makes an assumption about where the start of the bytes parameter will be. This is not a safe assumption to make, because as we’ve just learned, we can control where a bytes array will start using the offset field:

• For Calldata A the above Solidity will produce a selector value of d9caed12.
• For Calldata B the above Solidity will produce a selector value of 00000000. The behaviour inside execute() could therefore be different, even though the functional intent of the calldata appears the same.

The diagram below compares Calldata A and Calldata B and shows how the selector field is being read for each:

Although, in the above example, Calldata B contains padded unused data that is all zeroes, we can see how easy it would be to trick the selector field derivation. For Calldata B we could enter any 4 bytes we like at position 100, and the rest of the calldata is unaffected.

This is essentially the solution to the Damn Vulnerable DeFi puzzle #15 ABI Smuggling, the full Solidity solution is detailed here.