📖 Solidity Quick Reference

Welcome & how to use this page

This isn't a tutorial — it's a cheatsheet. The goal is one thing: when you're writing Solidity and need to remember "how does visibility work again?" or "which is the modern way to send ETH?", you land here, scan the relevant section in 30 seconds, and get back to work. Everything is organised for fast lookup: small concept blocks, comparison tables, copy-pasteable code, and pointers to the deeper labs when you want to actually build something with each idea.

Conventions in this reference

File anatomy — what every .sol file needs

Every Solidity source file has three mandatory ingredients at the top, then one or more contracts. The compiler emits two artifacts you'll use later: bytecode (what gets stored on-chain) and the ABI (what your frontend and other contracts need to call yours).

// SPDX-License-Identifier: MIT          // 1. license header — required
pragma solidity ^0.8.28;                // 2. compiler version pin — required

contract MyContract {                  // 3. one or more contracts
    // state, events, errors, functions…
}

The three mandatory parts

The compilation pipeline

Constructor — runs once, at deploy

The constructor is a special function that runs exactly once when the contract is deployed, then is gone forever from the bytecode. Use it to set initial state and lock in immutable configuration that should never change.

contract MyContract {
    address public immutable owner;       // set once, never changes
    uint256 public immutable cap;
    string  public name;                    // not immutable: strings can't be
    uint256 public totalSupply;             // mutable state

    constructor(string memory _name, uint256 _cap) {
        owner = msg.sender;                 // deployer's EOA address
        name  = _name;
        cap   = _cap;
    }
}

Rules to remember

Value types — copied on assignment

Value types are copied when passed around (between functions, into mappings, etc.) — like JavaScript's number or boolean. The EVM operates on a 256-bit word, so the canonical size is 256 bits. Anything smaller still occupies a full slot but adds masking overhead. Use uint256 for standalone variables; reach for smaller types only when you pack multiple into one storage slot.

Integers

Other value types

Reference types & data locations

Reference types hold dynamic-size data (strings, arrays, structs). Unlike value types, they live in one of three data locations — and the location decides whether you're passing a copy or a pointer. Get this wrong and you'll spend an hour wondering why a function mutation didn't stick.

The reference types

The three data locations

Mappings — the dictionary you'll use most

A mapping is Solidity's version of a hash-map / dictionary / object: lookup a key, get a value. It's by far the most common data structure on-chain — ERC-20 balances, NFT owners, ticket holders, donation tallies, you name it. The mental model is "infinite array initialised to zero": every possible key is pre-filled with the value type's default, and writing only allocates the slots you actually touch.

// Simple mapping: address → uint256
mapping(address => uint256) public balances;

balances[msg.sender] = 100;          // write
uint256 b = balances[msg.sender];   // read (returns 0 if never written)
delete balances[msg.sender];          // reset to default; refunds some gas

// Nested mapping: address → (tokenId → bool)
mapping(address => mapping(uint256 => bool)) public approved;

approved[owner][tokenId] = true;

// Mapping to a struct
struct User { uint256 balance; bool active; }
mapping(address => User) public users;
users[msg.sender].balance = 42;       // direct field assignment works

Rules & limitations

Visibility — who can call what

Every function and state variable carries one of four visibility modifiers. They answer the question "who is allowed to reach this". Getting the level wrong is the most common access-control bug in junior contracts — either you make something public that should have been internal, or you forget the modifier entirely (Solidity 0.5+ now requires you to specify one).

Visibility on state variables (properties)

State variables — the "properties" of a contract — accept the same visibility keywords, but the rules differ slightly from functions. The biggest one: only public, internal, and private are allowed on state variables. external is a function-only modifier (a variable cannot be "callable from outside but not from inside" — every state variable is always readable from inside its own contract). Default if you omit the keyword: internal.

contract Example {
    // public  — readable everywhere; compiler generates a free getter
    uint256 public totalSupply;        // → function totalSupply() external view returns (uint256)

    // internal (default) — this contract + subclasses; NO auto-getter
    uint256 internal reserve;          // readable inside, invisible from the ABI
    address admin;                    // same as `address internal admin;` — internal is the default

    // private — this contract only; subclasses can't even read it
    bytes32 private secretHash;        // see ⚠️ — still readable on-chain by anyone

    // external — NOT ALLOWED on state variables (compile error)
    // uint256 external badIdea;
}

State mutability — what a function can do with state and money

After visibility, every function carries a second label: its state mutability. This declares what the function is allowed to do with on-chain state and with ETH. The compiler enforces it — try to write storage from a view function and you get a build error. It also drives how the function is called: pure/view calls are free if you ask from outside the chain; everything else is a paid transaction.

Two transaction kinds you'll see in MetaMask

Globals — the variables that just exist

Solidity exposes a handful of magic variables that are always in scope. You don't import them or declare them — they're filled in by the EVM at execution time. These give your contract access to the calling context (who, how much, when) and to a few helpers.

The msg.* family — who's calling, with what

The block.* family — when, where, who's the miner

Other useful globals

Events & emit — talking to off-chain

Events are append-only logs that smart contracts write during execution. They cost a tiny fraction of storage gas, are immutable once mined, and — crucially — are indexed by every Ethereum node, so frontends, indexers (The Graph), and explorers (Etherscan) can subscribe to them in real time. This is how on-chain state communicates with off-chain UIs.

// Declaration: up to 3 indexed params, plus any number of non-indexed
event Transfer(
    address indexed from,
    address indexed to,
    uint256         amount      // not indexed
);

// Emit inside a function — exactly when state changes
function transfer(address to, uint256 amount) external {
    balances[msg.sender] -= amount;
    balances[to]          += amount;
    emit Transfer(msg.sender, to, amount);
}

The log shape — topics + data

Each emit produces a log record with up to four topics and a data blob:

Errors — three ways to revert

When something goes wrong, a function must revert — undoing all state changes from the current transaction and refunding the unused gas. Solidity gives you three ways to express this, but in modern code one of them dominates: custom errors. They're cheaper, more expressive, and Etherscan decodes them beautifully.

// 1. require — terse, with a string message
require(msg.value >= price, "insufficient payment");

// 2. revert with a string — equivalent, more flexible (can be inside if/else)
if (msg.value < price) revert("insufficient payment");

// 3. Custom error — declared once, revert with arguments (the modern way)
error InsufficientPayment(uint256 sent, uint256 required);

if (msg.value < price)
    revert InsufficientPayment(msg.value, price);

// 4. assert — for "should never happen" invariants only
assert(totalSupply == sum);   // since 0.8.0: reverts with Panic(uint256), gas refunded normally

Comparison

Modifiers — reusable function preconditions

A modifier is a wrapper around a function body. It runs code before (and optionally after) the function executes. The most common use is access control — define onlyOwner once, apply it to any function that should only run for the owner. Modifiers compile inline; there's no real runtime cost compared to writing the same checks directly.

contract Vault {
    address public immutable owner;
    error NotOwner();

    modifier onlyOwner() {
        if (msg.sender != owner) revert NotOwner();
        _;                              // run the wrapped function body here
    }

    constructor() { owner = msg.sender; }

    function withdraw(uint256 amount) external onlyOwner {
        payable(owner).transfer(amount);
    }

    function pause() external onlyOwner {  // reused — that's the point
        // …
    }
}

The _; placeholder

Inside a modifier, the underscore-semicolon _; marks "insert the function body here". Code before _; runs as a pre-check; code after runs as post-processing. Most modifiers only have pre-checks. If you forget the _;, the wrapped function never runs — the compiler doesn't warn you, but every call silently no-ops.

Common modifiers you'll see

Modifiers with arguments

Modifiers can take parameters, just like functions: modifier costs(uint256 price) { require(msg.value >= price); _; }, then apply function buy() external payable costs(0.1 ether) { … }. The arguments are evaluated at the call site of the wrapped function, so you can use other function arguments inside the modifier.

Receive & fallback — how a contract accepts plain ETH

Most ETH that enters a contract arrives through a normal payable function call (someone called buyTicket() and attached value). But what happens if someone sends ETH to the contract address with no function call at all — a bare transfer from MetaMask, a selfdestruct from another contract, or a call with empty data? Solidity provides two special functions for exactly this: receive() and fallback(). Knowing which one fires when is one of the most-asked Solidity interview questions.

contract Receiver {
    event EthReceived(address indexed from, uint256 amount);
    event FallbackCalled(address indexed from, uint256 amount, bytes data);

    // Plain ETH transfer, NO calldata. Must be external + payable. No name, no args.
    receive() external payable {
        emit EthReceived(msg.sender, msg.value);
    }

    // Calldata that doesn't match any function selector — or no receive() defined.
    // payable is OPTIONAL: omit it if you don't want fallback to accept ETH.
    fallback() external payable {
        emit FallbackCalled(msg.sender, msg.value, msg.data);
    }
}

The decision tree — which one fires?

When a transaction arrives at a contract, the EVM looks at two things: is msg.data empty, and is there a matching function selector? The flow:

receive() vs fallback() — quick comparison

The three ways to send ETH — and why you only need one

Solidity gives you three primitives for moving ETH from your contract to another address. Two are legacy and discouraged; one is the modern default. This is one of the most common interview questions for a Solidity dev — and one of the most common sources of "why did my contract break after the chain upgraded?" bugs. Skim the table, then read the rule.

address payable recipient = payable(someAddress);
uint256 amount = 1 ether;

// 1. .transfer — DEPRECATED. Reverts on failure. 2300-gas budget.
recipient.transfer(amount);

// 2. .send — DEPRECATED. Returns bool. 2300-gas budget. You must check the bool.
bool ok = recipient.send(amount);
if (!ok) revert TransferFailed();

// 3. .call{value:}("") — RECOMMENDED. Forwards all gas. Returns (bool, bytes).
(bool success, ) = recipient.call{value: amount}("");
if (!success) revert TransferFailed();

Side-by-side comparison

Why .call won — the short version