Solidity Smart Contracts: Complete Beginner Guide

The phrase "smart contract" trips a lot of beginners up. A smart contract is not a legal contract. It is a program. The program is deployed once, sits at an address on chain, and anyone in the world can call its functions by sending a transaction. The chain runs the code, updates the state, and records the outcome in a block. There is no central server, no deploy command after the first one, and no rollback if something goes wrong.

Solidity is the reason this is approachable. Before Solidity, writing for the EVM meant hand assembling opcodes. Solidity adds variables, functions, types, control flow, and inheritance, the same building blocks you find in any general purpose language. If you have written JavaScript, Python, or Java, the surface syntax of Solidity will feel familiar within an hour. The depth, the EVM specific quirks, the gas model, the security patterns, those take longer.

Solidity is open source. The compiler is called solc. It is maintained by the Ethereum Foundation and a community of contributors. New versions ship every few months. The current major line is 0.8, and pragmas at the top of every contract pin which compiler versions the file is allowed to compile against.

Solidity exists because the EVM by itself is too low level for everyday work. The EVM is a 256 bit stack machine that understands a few hundred opcodes. You can technically write contracts directly in EVM assembly using a language called Yul, and a small number of optimised libraries do exactly that. For everyone else, Solidity provides a sane abstraction. You declare a contract, write your business logic in something close to JavaScript, and let the compiler worry about which opcodes to emit and how to lay out storage slots.

Where does Solidity run? Anywhere the EVM runs. That list is long and growing. Ethereum mainnet is the original target. Layer 2 networks like Arbitrum, Optimism, Base, and zkSync are all EVM compatible. Sidechains and alternative L1s like Polygon, BNB Chain, Avalanche C Chain, Fantom, and Gnosis Chain run the same EVM. So do most testnets such as Sepolia and Holesky. A single Solidity contract, compiled once, can be deployed to any of them with no code changes. Only the gas costs and transaction speeds differ.

The use cases are equally broad. The vast majority of decentralised finance protocols (Uniswap, Aave, Compound, MakerDAO) are written in Solidity. Most NFT collections (the ERC721 and ERC1155 contracts) are Solidity. DAO governance modules, on chain games, tokenized real world assets, account abstraction wallets, prediction markets, identity systems, oracles, all Solidity. If something happens on an EVM chain and a regular user can interact with it, there is a Solidity contract behind it.

A simple way to picture it: you write .sol files, you run the compiler, you get bytecode and an ABI, you send that bytecode in a deployment transaction. The chain assigns the contract an address. From that moment on, your contract is part of the public state and anyone can interact with it.

Open Remix in your browser at remix.ethereum.org. You do not need to install anything. Create a new file called Counter.sol and paste this:

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

contract Counter {
    uint256 public count;

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

    function reset() public {
        count = 0;
    }
}

Five things happen here. The first line declares an SPDX license identifier so the compiler does not warn about missing licensing. The pragma tells the compiler to use any 0.8 series version. The contract Counter block is the contract itself. uint256 public count declares a state variable that automatically gets a getter. The two functions read and write that state.

Hit the green compile button in Remix. If there are no errors, switch to the Deploy tab, pick Remix VM (a sandbox EVM), and click Deploy. Your contract appears under Deployed Contracts. Click increment. Click count. You will see the number go up. That is a working smart contract. Storage is being read and written, transactions are being signed, gas is being measured. All of it runs locally in your browser.

You will spend the rest of your time in Solidity expanding on these primitives. State variables hold things, functions change them, and modifiers and events add layers of logic and observability around the changes. Every contract on Ethereum, no matter how complex, is built from the same shapes you just used.

When you declare a variable in Solidity, you state its type before its name. There is no type inference at the contract scope. A variable can live in three places: storage (persists on chain across transactions), memory (lives only during a function call), or calldata (read only inputs to external calls). Storage is expensive, memory is cheap, calldata is cheapest. Choosing where data lives is one of the first gas optimization habits to develop.

The numeric types are the workhorses. uint256 holds a non negative integer up to roughly 1.16 times 10 to the 77. There are also uint8, uint16, all the way up in steps of 8 bits. Smaller types do not save gas on their own, but they save storage when you can pack several into one 32 byte slot. The signed counterpart is int256 and friends. For booleans, see the bool type in Solidity.

The address type stores a 20 byte Ethereum address. It comes in two flavours: address and address payable. The payable variant can receive ether through .transfer(), .send(), or .call{value:...}(). The non payable form cannot, which is a safety feature. For text and binary, see the string type and the bytes type.

Beyond scalars, you compose state with reference types. Arrays come in fixed (uint256[10]) and dynamic (uint256[]) flavours. Structs let you bundle related fields into a custom type. Mappings are the workhorse of contract state. They look like hash maps but behave more like sparse arrays: every possible key already has a default value, you just write at the keys that matter. A typical balance tracker looks like this:

mapping(address => uint256) public balances;

struct Account {
    uint256 balance;
    bool isActive;
    uint64 lastSeen;
}

mapping(address => Account) public accounts;

The first line is enough to track every wallet's balance. The second pattern, mapping to a struct, is how almost every non trivial contract organises its state. You will see this shape in token contracts, vaults, lending pools, governance contracts, and almost everywhere money or identity is involved.

A function in Solidity has a name, optional parameters, an optional return type, a visibility modifier, and an optional state mutability keyword. Here is the shape:

function transfer(address to, uint256 amount)
    public
    returns (bool success)
{
    require(balances[msg.sender] >= amount, "insufficient");
    balances[msg.sender] -= amount;
    balances[to]         += amount;
    emit Transfer(msg.sender, to, amount);
    return true;
}

The visibility level determines who can call the function. There are four levels in Solidity. They are not interchangeable, and choosing wrong is one of the most common security mistakes in beginner code. The full deep-dive lives in functions and visibility in Solidity.

Then there are the state mutability keywords, which tell the compiler what your function touches. view says the function reads state but never writes. pure goes further: it neither reads nor writes state. Both can be called for free as off chain reads. payable is the opposite end, marking a function that is allowed to receive ether along with the call. If you forget payable on a deposit function, every transaction that sends ether to it will revert.

Conditionals use the familiar if, else if, and else keywords. Solidity also has require, assert, and revert for guard conditions. require is the one you will use most: it checks a condition and reverts the transaction with an optional message if it fails. Failed requires refund all unused gas.

Loops behave like their C and JavaScript equivalents. The for loop is the workhorse. while and do while exist but are rare in production code because they are easier to get wrong. break and continue work as expected. There is one important rule: never write a loop where the iteration count depends on data that an attacker can grow without limit. A loop over a user controlled array can be made arbitrarily long, run out of gas, and brick the function permanently. The convention is to either cap the iteration count, or pull the loop off chain and have users settle results in batches.

Modifiers are a Solidity specific construct that wrap functions in reusable preconditions. They are how access control is expressed idiomatically:

address public owner;

modifier onlyOwner() {
    require(msg.sender == owner, "not owner");
    _;
}

function setFee(uint256 newFee) public onlyOwner {
    fee = newFee;
}

The underscore inside the modifier is where the body of the wrapped function gets injected. Anything before the underscore runs as a precondition, anything after runs as a postcondition. OpenZeppelin's Ownable and AccessControl contracts ship modifiers like this in production grade form. You almost never need to write your own from scratch.

The contract below lets users deposit ether, track their own balance, withdraw their funds, and lets the contract owner pause new deposits in an emergency. It is small enough to read in one sitting and large enough to be representative of real Solidity code.

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

contract SimpleBank {
    address public owner;
    bool    public paused;

    mapping(address => uint256) public balances;

    event Deposit(address indexed user, uint256 amount);
    event Withdraw(address indexed user, uint256 amount);
    event PausedChanged(bool paused);

    error NotOwner();
    error Paused();
    error InsufficientBalance();

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

    modifier whenNotPaused() {
        if (paused) revert Paused();
        _;
    }

    constructor() {
        owner = msg.sender;
    }

    function deposit() external payable whenNotPaused {
        balances[msg.sender] += msg.value;
        emit Deposit(msg.sender, msg.value);
    }

    function withdraw(uint256 amount) external {
        if (balances[msg.sender] < amount) revert InsufficientBalance();
        balances[msg.sender] -= amount;
        (bool ok, ) = payable(msg.sender).call{value: amount}("");
        require(ok, "transfer failed");
        emit Withdraw(msg.sender, amount);
    }

    function setPaused(bool value) external onlyOwner {
        paused = value;
        emit PausedChanged(value);
    }

    function totalDeposited() external view returns (uint256) {
        return address(this).balance;
    }
}

Walk through it once. The contract declares two flags (the owner and a pause switch), one mapping for balances, three events, and three custom errors. The constructor runs once at deploy time and sets the owner to whoever sent the deployment transaction. The two modifiers wrap functions in their preconditions. The four functions cover the user actions and the admin action.

Notice the patterns. Every state mutating function emits an event so that off chain indexers can rebuild the story. The withdraw function updates state before sending ether (the checks effects interactions pattern that prevents reentrancy). The owner check uses a custom error rather than a string, which costs less gas. The deposit function is external payable because external is cheaper for the simple case and payable is required to receive ether. None of this is optional in production code.

The pragma ^0.8.0 already protects you from the historical integer overflow class of bugs because the compiler inserts checks by default. Older code on 0.7 and below required SafeMath. If you are reading legacy contracts, that is the first thing to look for.

The single best habit you can develop early is to read OpenZeppelin's contracts source code. Their ERC20, ERC721, Ownable, AccessControl, ReentrancyGuard, and Pausable contracts are short, beautifully written, and audited by the entire industry. Reading them is how you learn what production grade Solidity looks like.

Suggested reading order for a complete picture: uint → int → bool → address → string → bytes → mapping → arrays → structs → functions and visibility → modifiers → events.