Solidity Assembly, Part 3: Reading a Contract Nobody Explained to You

This is the last of four parts. Part 1 compiled a contract and read its opcodes. Part 2 covered writing assembly yourself.

This part emulates the situation you're actually in when you look at somebody else's contract. Everything below is run against live mainnet, and every number is real output rather than an example.

Start with the question that matters.

Who can replace this code?

Take Aave's v3 lending pool at 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2. Billions of dollars of deposits sit behind it.

That address does not contain Aave's lending logic. It is a proxy. It holds almost no code of its own and forwards every call to another contract, and the address it forwards to can be changed.

So the question is not what the source says the pool does. The question is what code runs there right now, and who is allowed to swap it. Neither is answerable from Solidity, because both live in storage.

Reading it

Real output:

An address is 20 bytes and a storage slot is 32, so the value is left-padded with twelve zero bytes. Strip them and you have the answer:

That is the contract actually executing when anyone deposits into Aave. Check the sizes and the split is obvious:

The proxy is a doorway. The building is somewhere else.

Why that specific slot?

That long hex number is not arbitrary.

A proxy runs the implementation's code in the proxy's own storage. So if the proxy kept the implementation address in slot 0, and the implementation declared any state variable of its own, that variable would also be slot 0. One would overwrite the other.

ERC-1967 solves this by choosing a slot nothing else can land on. The address is stored at:

Two reasons that works. The compiler hands out slots starting at 0 and counting up, so it will never reach a number that large.

There are two more standard slots, derived the same way:

I recomputed all three rather than copying them from the spec, and they match.

The admin slot is empty, and that is not good news

Read Aave's admin slot and you get nothing:

An empty standard slot means the authority is not there. It does not mean the authority does not exist.

Aave's proxy stores its admin as an immutable. Immutables do not use storage at all. The compiler reserves space for them inside the contract's code, and the constructor writes the value into those bytes before the code is deployed. So the answer is sitting in the bytecode, in plain sight, if you know to look:

That address appears six times in the proxy's code. It is Aave's PoolAddressesProvider, and it is what controls upgrades.

The general lesson: when a standard slot is empty, the authority moved, and the two places to look next are the contract's own code and a different contract entirely.

Not every proxy follows the standard

ERC-1967 was finalized in 2019. Plenty of important contracts predate it.

USDC is one. 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 is a proxy, but its ERC-1967 implementation slot is empty because it uses the older ZeppelinOS convention:

So the code behind every USDC transfer lives at 0x43506849d7c04f9138d1a2050bbf3a0c054402dd, and Circle can change it.

Checking the standard slot first is still right. It just means an empty result sends you looking rather than telling you there is nothing to find.

Reading a balance out of raw storage

Proxy slots are fixed constants. Now the general skill: finding a value the compiler placed dynamically.

Take a token balance. A mapping(address => uint256) balances could hold billions of entries, so the compiler cannot lay them out sequentially. It does not store the keys at all. Instead it computes a location from the key:

That is the whole rule. Hash the key together with the slot the mapping was declared at, and the result is where the value lives.

USDC declares its balances mapping at slot 9. Take Binance's hot wallet at 0x28C6c06298d514Db089934071355E5743bf21d60:

Read that slot:

That is 50,828,467,320. USDC has six decimals, so 50,828.47 USDC. Now check the arithmetic against the contract itself:

Identical. That is the point of the exercise: you computed where a value lives from first principles and read it without calling any function the contract chose to expose.

Both commands are pinned to block 25,775,301 with --block. A hot wallet's balance changes every few minutes, so without the pin the two reads would disagree simply because time passed between them. Anyone can reproduce these exact numbers.

Two things that follow. A mapping's declared slot 9 stays permanently empty, reserved so neighbours cannot collide with it, so scanning for non-zero slots will never reveal a mapping exists. And nested mappings apply the rule twice: allowance[owner][spender] is a hash of the spender against the result of hashing the owner, not one hash of both.

Finding functions without an ABI

The last piece. A contract's code begins with a dispatcher that compares the first four bytes of your calldata against a list of known values and jumps accordingly. Those four bytes are the function selector, the first four bytes of keccak256 over the function's signature:

The selectors are sitting in the bytecode as PUSH4 instructions, opcode 0x63. Pull them out and you have the contract's external surface without an ABI:

Run that against USDC's proxy and the real ones that come back include:

Seeing upgradeTo in a dispatcher tells you the contract is upgradeable before you read a line of source.

That grep also returns 0x616c6c20, 0x68616e67 and 0x6f6e7472, which are not selectors at all. They are fragments of revert strings that happen to sit after a 0x63 byte: "all ", "hang", "ontr". A naive byte scan cannot tell code from data. Resolve everything through cast 4byte and discard what does not come back, or read the dispatcher properly rather than grepping the whole file.

Securing the unseen

Four questions you can now answer about any address, without an ABI, without verified source, and without anyone's cooperation.

Is it a proxy, and what does the implementation slot hold right now? If that slot is empty, is it using an older convention, or has the authority moved into the code? Who or what is in the admin slot, and is that an ordinary wallet or a contract with its own rules? Does the dispatcher contain upgradeTo or upgradeToAndCall?

An audit tells you what a version of the source did on the day somebody read it. Storage tells you what the contract points at right now.

Learn more at 0xhades.io/research