T7 · Solidity Basics

A Real-World Problem

The product team wants deposit escrow: users put money in, can withdraw it at any time, and the platform can step in when a dispute arises.

You have built dozens of services like this and could put together a first version in twenty minutes. But this time, “going live” is unlike any launch you know:

• The code is public. Anyone can decompile it, and most projects publish the source themselves.
• The database is public. The whole world can inspect how much each user deposited.
• There is no Nginx, gateway, or login page. Anyone can call any externally exposed function directly, using their own script without visiting your frontend.
• There is no staged rollout, rollback, or hotfix. Changing one line of code means changing the address.

The same business logic becomes something else in this environment. Before writing it, answer one question: What does a contract actually become after deployment?

Thought Experiment

Imagine a deployed contract as a vending machine in a public square.

It sits at a fixed location (an address). Its mechanism is welded in place (the code cannot change). The goods and money inside belong to the machine (storage). The panel has a row of buttons (external functions).

Now add four ways it differs from a real vending machine:

1. There are no business hours and no attendant. Anyone can press any button at any time.
2. The glass is completely transparent. Everyone can see how much money is inside and what each compartment holds. There is no “admin-only view.”
3. The person pressing the buttons chooses their order and frequency. No one guarantees they will follow your intended flow. They can press only the third button ten thousand times.
4. The machine knows who is pressing. Each press carries an identity marker that cannot be forged.

Point 4 is your only foothold. In a contract, “only I can do this” has just one expression: when this button is pressed, check whether the person pressing it is me.

Put the original deposit escrow into this machine. Anyone can press Deposit (reasonable). Anyone can press Withdraw (but only for their own money). What should the “platform intervention” button look like? Who can press it, and what happens when they do?

Your Decision

How should the “platform intervention” button work? Choose one of four designs.

What Happens

Put the four choices together and the same structure emerges:

Three points are worth remembering:

First, a permission is code, not a promise. “We will not touch user funds” on a website means nothing. Either the function does not exist in the code at all, or it exists but requires a two-day wait. Readers will inspect your contract, not your website.

Second, the granularity of permissions determines the scale of an incident. Putting both “pause” and “withdraw” under the same owner ties a small power and a large one to the same key.

Third, the chain will not automatically tell others what happened. The “announcement” above works because you deliberately emit a record. If you merely change a variable without emitting a record, monitoring systems and users will not see it. T1 explained that observability is part of contract design, not a built-in feature of the chain. This chapter makes that idea concrete.

Build a Model

A deployed contract is four things joined at one address.

0x1234… (one address)
 ├─ Code       Fixed at deployment; cannot change unless you designed an upgrade path in advance
 ├─ Storage    Persistent, public, and expensive. There are no truly “private fields” here
 ├─ Entrances  List of externally visible functions = list of attack surfaces
 └─ Records    Events deliberately emitted during execution, readable only offchain

Translate your backend habits one by one and the differences become clear:

In code, the smallest deposit contract looks like this:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.4;   // Custom errors are available from 0.8.4

contract Vault {
    // ── Storage: these four variables are this contract's entire memory ──
    address public owner;
    bool public depositsPaused;
    mapping(address => uint256) public balanceOf;
    uint256 public totalDeposits;

    // ── Records: the only voice offchain systems can hear ──
    event Deposited(address indexed account, uint256 amount);
    event Withdrawn(address indexed account, uint256 amount);
    event DepositsPausedSet(bool paused);
    event OwnerTransferred(address indexed from, address indexed to);

    // ── Reasons for refusal: cheaper than require strings, and callers can identify them by type ──
    error NotOwner();
    error DepositsArePaused();
    error ZeroAmount();
    error ZeroAddress();
    error InsufficientBalance(uint256 requested, uint256 available);
    error TransferFailed();

    modifier onlyOwner() {
        if (msg.sender != owner) revert NotOwner();
        _;
    }

    constructor() {
        owner = msg.sender;
        emit OwnerTransferred(address(0), msg.sender);
    }

    function deposit() external payable {
        if (depositsPaused) revert DepositsArePaused();
        if (msg.value == 0) revert ZeroAmount();
        balanceOf[msg.sender] += msg.value;
        totalDeposits += msg.value;
        emit Deposited(msg.sender, msg.value);
    }

    function withdraw(uint256 amount) external {
        if (amount == 0) revert ZeroAmount();
        uint256 available = balanceOf[msg.sender];
        if (amount > available) revert InsufficientBalance(amount, available);

        // Update the ledger before paying. Reverse this order and things go badly; see T28
        balanceOf[msg.sender] = available - amount;
        totalDeposits -= amount;
        emit Withdrawn(msg.sender, amount);

        (bool ok, ) = msg.sender.call{value: amount}("");
        if (!ok) revert TransferFailed();
    }

    // The administrator can close the valve, but cannot touch anyone's balance
    function setDepositsPaused(bool paused) external onlyOwner {
        depositsPaused = paused;
        emit DepositsPausedSet(paused);
    }

    function transferOwner(address newOwner) external onlyOwner {
        if (newOwner == address(0)) revert ZeroAddress();
        emit OwnerTransferred(owner, newOwner);
        owner = newOwner;
    }
}

When reading this code, read it four times through these four lenses. That is more useful than reading the syntax line by line:

1. Entry points: deposit, withdraw, setDepositsPaused, transferOwner. Four entry points mean four attack surfaces. For every new external function, ask again: “What happens if anyone calls it?”
2. Permissions: only two functions use onlyOwner, and neither can touch balanceOf. That is the “can only close the valve” row of the table above, expressed in code.
3. Order of state changes: withdraw updates the ledger and emits the event before sending the money. That order is not a matter of style.
4. Observability: every state change has an event, with key fields indexed. Offchain systems can reconstruct everyone’s balances from those four events. You designed that ability; it is not free.

One more detail is easy to miss: mapping looks like a hash table, but you cannot iterate over it. You cannot get a list of “all addresses that have deposited.” To get that list, you must maintain a separate array, which brings its own costs and attack surface. This is one of the most common moments when backend intuition fails in contracts.

What It Is Called

Hands-on

AI Lab

Step one:
Complete the NatSpec comments for this contract. For every function, explain what it does,
who can call it, when it reverts, which state it changes, and which events it emits.
Do not change any code logic.

Step two:
Now act as an auditor. For each function, answer: if a completely unknown address calls it
with arbitrary arguments and any number of times, what is the worst that can happen?
Describe only situations actually possible in the code. Do not suggest improvements.

Real-World Case

Change One Variable

Takeaway Questions

Chapter Check