Primeiros Passos
Básico de Contratos
Solidity é a linguagem principal para smart contracts da Ethereum. pragma define a versão do compilador. Um contrato é como uma classe. Funções podem ser public, private, view (somente leitura) ou payable.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract SimpleStorage {
uint256 storedData;
function set(uint256 x) public {
storedData = x;
}
function get() public view returns (uint256) {
return storedData;
}
}Pragma e Versão do Compilador
pragma especifica a versão do compilador. ^0.8.0 aceita qualquer patch 0.8.x. Para produção, fixe a versão exatamente (0.8.19) para evitar surpresas. Sempre inclua o pragma no topo de cada arquivo .sol.
// Lock to a single version
pragma solidity 0.8.19;
// Allow patches (^0.8.0 means >=0.8.0 <0.9.0)
pragma solidity ^0.8.0;
// Range of versions
pragma solidity >=0.8.0 <0.9.0;
// Experimental features (ABIEncoderV2 in older versions)
pragma experimental ABIEncoderV2;Comentários e NatSpec
Comentários NatSpec (/// ou /** */) geram documentação. @notice é para usuários finais, @dev para desenvolvedores, @param descreve parâmetros, @return descreve valores de retorno. Eles são capturados por ferramentas como Etherscan e Remix.
// Single-line comment
/* Multi-line
comment */
/// @title A Simple Contract
/// @author Alice
/// @notice This is visible to end users
/// @dev This is for developers
contract Commented {
/// @notice Sets the value
/// @param _x The new value
/// @dev Internal details here
function set(uint256 _x) public {}
}Licença SPDX
Desde o Solidity 0.6.8, o identificador de licença SPDX é obrigatório no topo do arquivo. Ele ajuda ferramentas e usuários a entender como o código pode ser reutilizado. Use MIT para open-source permissivo, GPL-3.0 para copyleft, ou UNLICENSED para código privado.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
// Common licenses:
// MIT - permissive
// GPL-3.0 - copyleft
// Apache-2.0 - permissive with patent grant
// UNLICENSED - private/no license
// BSD-2-Clause, BSD-3-Clause
contract Licensed {}Estrutura de Arquivo e Imports
Imports trazem contratos, bibliotecas ou interfaces. Use {Nome} para importar só itens específicos. Caminhos relativos funcionam como esperado. A palavra-chave 'is' estabelece herança. Arquivos tipicamente têm um contrato principal, mas podem conter vários.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "./OtherContract.sol";
import {SpecificContract, Helper} from "./Library.sol";
import * as Lib from "./Library.sol"; // namespace
import "openzeppelin/contracts/token/ERC20.sol";
contract MyContract is OtherContract {
// ...
}Tipos de Valor
Inteiros (uint / int)
uint = inteiro sem sinal (sem negativos), int = com sinal. Os tamanhos vão de 8 a 256 em passos de 8. uint assume uint256. Desde a 0.8.0, a aritmética auto-verifica overflow/underflow e reverte. Use type(T).max / type(T).min para obter os limites.
uint256 public bigNumber = 1 ether; // 10^18
uint8 public small = 255; // max 255
int256 public signed = -100;
uint public defaultSize = 42; // uint256 by default
// Arithmetic
uint256 a = 10;
uint256 b = 3;
uint256 sum = a + b; // 13
uint256 diff = a - b; // 7 (0.8+ reverts on underflow)
uint256 product = a * b; // 30
uint256 quotient = a / b; // 3
uint256 remainder = a % b; // 1
uint256 power = a ** 2; // 100
// Type min/max (0.8+)
uint256 max = type(uint256).max;
int256 min = type(int256).min;Booleano
bool só pode ser true ou false. && e || curto-circuitam, ou seja, o lado direito só é avaliado se necessário. O valor padrão é false. Booleanos custam mais gas que uint256 em alguns contextos (empacotamento de storage).
bool public flag = true;
bool public negated = !flag; // false
bool public and = flag && false; // false
bool public or = flag || false; // true
// Short-circuit evaluation
bool result = (flag && expensiveCall()); // skips call if flag false
bool result2 = (!flag || expensiveCall());
// Equality
bool equal = (1 == 1); // true
bool notEq = (1 != 2); // true
// Boolean defaults to false
bool public defaultValue; // falseAddress
address guarda um endereço Ethereum de 20 bytes. address payable pode receber Ether (tem funções transfer/send). Use payable(x) para converter. Endereços têm a propriedade .balance (em wei). Sempre verifique literais de endereço contra o checksum EIP-55 para capturar erros de digitação.
address public owner = msg.sender;
address payable public treasury = payable(owner);
// Balance (read-only)
uint256 bal = owner.balance; // in wei
// Send Ether (payable address only)
treasury.transfer(1 ether);
bool sent = treasury.send(1 ether);
// Convert from address to payable
address addr = 0x123...;
address payable payableAddr = payable(addr);
// Address literals (checksummed)
address public constant BURN = 0x000000000000000000000000000000000000dEaD;
// Compare addresses
bool same = (addr1 == addr2);Bytes e Arrays de Bytes
Bytes fixos (bytes1..bytes32) são baratos e usados para hashes/seletores. bytes dinâmico é para dados binários crus; string é para texto UTF-8. Use bytes32 para hashes (keccak256 retorna bytes32). bytes.concat() (0.8.4+) é mais barato que abi.encodePacked para arrays de bytes.
// Fixed-size byte arrays (bytes1 to bytes32)
bytes32 public hash = keccak256(abi.encodePacked("data"));
bytes1 public b1 = 0x41; // single byte
bytes4 public selector = bytes4(keccak256("transfer(address,uint256)"));
// Dynamic byte arrays
bytes public dynamic = "hello";
bytes public empty;
// String vs bytes
string public text = "Hello"; // UTF-8 string
bytes public raw = bytes(text);
// Operations on fixed bytes
bytes32 data = keccak256(abi.encode("x"));
bytes1 first = data[0]; // access by index
uint256 length = data.length; // 32
// Concatenation
bytes memory combined = bytes.concat(bytes("a"), bytes("b"));Enums
Enums definem um conjunto finito de valores nomeados. São guardados como uint8 (máximo 256 membros). O valor padrão é o primeiro membro (índice 0). Converta entre enum e uint usando casts. type(NomeEnum).max dá o membro mais alto.
contract EnumExample {
enum Status { Pending, Active, Paused, Closed }
Status public status = Status.Pending;
function activate() public {
require(status == Status.Pending, "Not pending");
status = Status.Active;
}
function next() public {
// Cast to uint to do math
uint current = uint(status);
if (current < uint(type(Status).max)) {
status = Status(current + 1);
}
}
// Default value is the first member (Pending)
Status public defaultValue; // Pending
}Conversão e Casting de Tipos
Conversões implícitas só acontecem quando não há perda de dados possível (uint8 -> uint256). Para conversões estreitadoras (uint256 -> uint8) ou com/sem sinal, use casts explícitos. Converter um int negativo para uint produz um número enorme, devido ao complemento de dois.
// Implicit conversion (safe, widening)
uint8 small = 10;
uint256 big = small; // OK: uint8 fits in uint256
// Explicit conversion (narrowing, may lose data)
uint256 large = 300;
uint8 narrow = uint8(large); // truncates to 44 (300 % 256)
// Address conversion
address addr = 0xAb8483F64d9C6d1Ec37F8D2C4fA6bA5d5C5e5C5e;
address payable payableAddr = payable(addr);
// Bytes conversion
bytes32 b32 = bytes32(uint256(42));
uint256 num = uint256(b32);
bytes4 selector = bytes4(keccak256("foo()"));
// String <-> bytes
string memory s = "hi";
bytes memory bs = bytes(s);
string memory s2 = string(bs);
// int <-> uint (explicit, watch for negatives)
int256 signed = -5;
uint256 unsigned = uint256(signed); // huge number!Tipos de Referência
String
Strings no Solidity são arrays de bytes UTF-8 — length() retorna contagem de bytes, não de caracteres (emoji/caracteres multibyte diferem). Igualdade deve ser verificada via hash keccak256. string.concat (0.8.12+) é mais barato que abi.encodePacked. Strings são caras em gas.
contract Strings {
string public greeting = "Hello, World!";
function concat(string memory a, string memory b)
public pure returns (string memory)
{
return string.concat(a, " ", b); // 0.8.12+
}
function length(string memory s) public pure returns (uint256) {
return bytes(s).length; // byte length, not char count
}
function equals(string memory a, string memory b)
public pure returns (bool)
{
return keccak256(bytes(a)) == keccak256(bytes(b));
}
// Storage string (state variable)
string public stored;
function set(string memory s) public { stored = s; }
}Arrays (Fixos e Dinâmicos)
Arrays fixos [N] têm tamanho em tempo de compilação; arrays dinâmicos [] crescem com push/pop. Arrays em memória precisam ser criados com 'new Tipo[](tamanho)'. Ler/escrever arrays de storage custa gas; prefira memory para dados temporários. push() retorna uma referência na 0.6+.
contract Arrays {
// Fixed-size array
uint256[5] public fixedArr = [1, 2, 3, 4, 5];
// Dynamic array
uint256[] public dynamicArr;
function pushPop() public {
dynamicArr.push(10); // append: [10]
dynamicArr.push(20); // [10, 20]
dynamicArr.pop(); // remove last: [10]
}
function getLength() public view returns (uint256) {
return dynamicArr.length;
}
function iterate() public view returns (uint256 sum) {
for (uint256 i = 0; i < dynamicArr.length; i++) {
sum += dynamicArr[i];
}
}
// Array of arrays (2D)
uint256[][] public matrix;
// Memory array (must have fixed length when created)
function memArray() public pure returns (uint256[] memory) {
uint256[] memory arr = new uint256[](3);
arr[0] = 1; arr[1] = 2; arr[2] = 3;
return arr;
}
}Structs
Structs agrupam campos relacionados. Podem ser guardadas em storage, memory ou passadas como argumentos de função. Defina-as no nível do arquivo ou do contrato. Inicializar com campos nomeados {campo: valor} é mais claro; posicional é mais curto. Valores de mapping não podem ser estruturas acessadas diretamente como uma unidade em versões antigas.
contract Structs {
struct User {
address wallet;
uint256 balance;
bool active;
string name;
}
// Single struct (storage)
User public owner;
User[] public users; // array of structs
mapping(address => User) public userByAddr;
function createUser(string memory name) public {
User memory u = User({
wallet: msg.sender,
balance: 100,
active: true,
name: name
});
users.push(u);
}
// Shorter syntax
function createShort() public {
users.push(User(msg.sender, 50, true, "anon"));
}
// Update a field
function deactivate(uint256 index) public {
users[index].active = false; // direct storage write
}
}Mappings
Mappings são tabelas hash: keccak256(chave) => valor. Não têm comprimento e não podem ser iterados. Chaves podem ser tipos de valor (uint, address, bytes, enum); valores podem ser qualquer coisa. Mappings aninhados permitem consultas multi-chave. Para iterar, mantenha um array separado de chaves. delete reseta uma chave ao seu valor zero.
contract Mappings {
// keyType => valueType
mapping(address => uint256) public balances;
mapping(address => mapping(address => uint256)) public allowance;
mapping(address => bool) public isRegistered;
function setBalance(uint256 amount) public {
balances[msg.sender] = amount;
}
function approve(address spender, uint256 amount) public {
allowance[msg.sender][spender] = amount;
}
function register() public {
isRegistered[msg.sender] = true;
}
// Iterable mapping pattern
address[] public userList;
mapping(address => bool) public exists;
function addUser(address u) public {
if (!exists[u]) {
userList.push(u);
exists[u] = true;
}
}
// CANNOT iterate or get length of a mapping directly
// CANNOT delete a mapping, only individual keys
function remove() public {
delete balances[msg.sender]; // sets to 0
}
}Localizações de Dados (storage / memory / calldata)
storage = estado persistente on-chain (caro). memory = temporário, vive durante a chamada da função (barato). calldata = somente leitura, só para entradas de funções external (o mais barato). Sempre use calldata para argumentos de funções external que você só lê. Localização padrão: variáveis de estado são storage; tipos complexos locais de funções assumem memory.
contract DataLocations {
string public stateVar; // storage (state)
function f(string calldata input) external {
// calldata: read-only, only for external function args
string memory local = input; // memory: temporary copy
stateVar = local; // writes to storage
// storage reference (only inside a function)
string storage ref = stateVar;
ref = "new value"; // modifies stateVar
}
// External params can be calldata (cheapest)
function g(string calldata s) external pure returns (bytes32) {
return keccak256(bytes(s));
}
// Public/internal params default to memory
function h(string memory s) public pure returns (uint256) {
return bytes(s).length;
}
// Assignment rules:
// storage -> storage: reference (both point to same slot)
// memory -> memory: reference (both point to same memory)
// storage <-> memory: copy
}Estruturas Aninhadas
Structs podem conter arrays, mappings (só em storage) e outras structs. Acessar campos de structs aninhadas via uma referência de storage é eficiente em gas. Cuidado com aninhamento profundo — aumenta o uso de slots de storage e o custo de implantação. Mapping-de-struct é o padrão de banco de dados on-chain mais comum.
contract Nested {
struct Order {
uint256 id;
uint256 amount;
Item[] items;
}
struct Item {
string sku;
uint256 qty;
}
mapping(uint256 => Order) public orders;
Order[] public allOrders;
function addOrder(uint256 id, string memory sku, uint256 qty) public {
Order storage o = orders[id];
o.id = id;
o.amount += qty * 1 ether;
o.items.push(Item(sku, qty));
}
// Mapping of struct arrays
mapping(address => Item[]) public userItems;
// Struct in a struct
struct Profile {
User user;
uint256 score;
}
struct User {
address addr;
string name;
}
Profile public profile;
}Variáveis de Estado
Variáveis de Estado Públicas e Privadas
Variáveis de estado públicas geram automaticamente uma função getter. private restringe o acesso ao próprio contrato; internal permite também subclasses. O padrão é internal. CRÍTICO: 'private' NÃO significa secreto — qualquer dado da blockchain é publicamente legível. Use criptografia/hashing se precisar de confidencialidade.
contract Visibility {
uint256 public publicVar = 1; // auto getter created
uint256 private privateVar = 2; // only this contract
uint256 internal internalVar = 3; // this + subclasses
// No 'external' for state variables
// internal is the default
uint256 defaultVar = 4; // internal
function readPrivate() public view returns (uint256) {
return privateVar; // readable from inside
}
// 'private' only means 'not via other contracts'.
// The data is still visible on-chain!
}
// public creates an automatic getter:
// function publicVar() external view returns (uint256) { return publicVar; }Variáveis Constantes
Variáveis constant são avaliadas em tempo de compilação e embutidas no bytecode — custam zero gas em runtime (sem SLOAD). Só tipos de valor (uint, address, bytes etc.) podem ser constant. O valor deve ser uma expressão de tempo de compilação. Use constant para valores fixos como MAX_SUPPLY, DECIMALS, endereços.
contract Constants {
// constant: evaluated at compile time, inlined into code
uint256 public constant MAX_SUPPLY = 1_000_000 * 10**18;
address public constant DEAD = 0x000000000000000000000000000000000000dEaD;
uint8 public constant DECIMALS = 18;
// Must be value types, assigned a literal/expression
// No assignment in constructor
// Numeric separators (1_000_000) work since 0.8.0
function compute() public pure returns (uint256) {
return MAX_SUPPLY / 2; // inlined, no SLOAD
}
}Variáveis Immutable
Variáveis immutable são definidas uma vez no construtor e depois somente leitura. São guardadas no bytecode (não no storage), então leituras custam menos que variáveis de estado comuns. Diferente de constant, immutable pode usar argumentos do construtor e valores de runtime. Use immutable para coisas definidas na implantação, como owner, nome do token ou config específica da chain.
contract Immutable {
// immutable: set once in constructor, then read-only
address public immutable owner;
uint256 public immutable creationBlock;
constructor(address _owner) {
owner = _owner;
creationBlock = block.number;
}
// Can be any value type
// Cheaper than regular state vars (no SLOAD slot, uses code)
// More flexible than constant (can use constructor args)
function check() public view returns (bool) {
return msg.sender == owner; // cheap read
}
}
// Use case: factory-deployed contracts with constructor args
contract Factory {
Child[] public children;
function create(address owner) public {
children.push(new Child(owner));
}
}
contract Child {
address public immutable owner;
constructor(address _owner) { owner = _owner; }
}Variáveis Globais (msg, tx, block)
msg fornece o contexto da chamada: msg.sender (chamador imediato), msg.value (wei enviado), msg.data (calldata cru), msg.sig (seletor da função). tx dá informação da transação: tx.origin (a EOA, NÃO recomendado para auth). block dá o bloco atual: block.timestamp, block.number, block.chainid, block.coinbase. Nunca use tx.origin para autorização — use msg.sender.
contract Globals {
function msgVars() public view returns (
address sender,
bytes4 selector,
uint256 value,
bytes memory data
) {
sender = msg.sender; // caller address
selector = msg.sig; // function selector
value = msg.value; // wei sent with tx
data = msg.data; // full calldata
}
function txVars() public view returns (address origin, uint256 gasprice) {
origin = tx.origin; // EOA that started the tx
gasprice = tx.gasprice; // gas price in wei
}
function blockVars() public view returns (
uint256 number,
uint256 timestamp,
address miner,
uint256 chainId
) {
number = block.number; // current block height
timestamp = block.timestamp; // current block time (uint256 in 0.8+)
miner = block.coinbase; // block miner/validator
chainId = block.chainid; // chain ID
}
}Propriedades de Bloco e Tx
blockhash() só retorna hashes dos últimos 256 blocos; mais antigos retornam 0. block.timestamp é definido pelo minerador e pode variar ~15 segundos — nunca use para precisão de tempo ou aleatoriedade. block.basefee vem do EIP-1559. gasleft() substitui o msg.gas obsoleto. chainid é crítico para proteção contra replay.
contract BlockProps {
function getBlockInfo() public view returns (
uint256 number,
uint256 timestamp,
uint256 gasLimit,
uint256 gasPrice,
uint256 baseFee
) {
number = block.number;
timestamp = block.timestamp;
gasLimit = block.gaslimit;
gasPrice = tx.gasprice;
baseFee = block.basefee; // EIP-1559 (London)
}
function getChainId() public view returns (uint256) {
return block.chainid;
}
function getPrevHash(uint256 n) public view returns (bytes32) {
require(n < 256, "out of range");
return blockhash(block.number - n); // last 256 blocks
}
function gasLeft() public view returns (uint256) {
return gasleft(); // remaining gas
}
}Funções
Sintaxe de Função
Sintaxe de função: function nome(params) visibilidade mutabilidade returns(...). A visibilidade (public/external/internal/private) é obrigatória. A mutabilidade (pure/view/payable) é opcional, mas recomendada. Múltiplos valores de retorno são suportados. Retornos nomeados permitem atribuir diretamente a eles e pular a palavra-chave return.
contract Func {
// function name(params) <visibility> <state-mutability> returns(...)
function add(uint256 a, uint256 b)
public
pure
returns (uint256)
{
return a + b;
}
// Multiple returns
function split(uint256 x)
public pure returns (uint256, uint256)
{
return (x / 2, x % 2);
}
// Named returns (no explicit return needed)
function named(uint256 x)
public pure returns (uint256 half, uint256 rest)
{
half = x / 2;
rest = x % 2;
// return statement optional
}
// Destructure returns
function caller() public pure returns (uint256) {
(uint256 h, uint256 r) = named(10);
return h + r;
}
}Funções View
Funções view podem ler o estado, mas não modificá-lo. Chamadas externamente via eth_call, são gratuitas (sem taxa de gas). Chamadas internamente de uma função que modifica, consomem gas. Use view para qualquer função que só lê estado — isso sinaliza a intenção e permite leituras gratuitas off-chain.
contract ViewFn {
uint256 public counter = 0;
// view: can READ state but not modify
function getCount() public view returns (uint256) {
return counter; // reading state
}
function doubleCount() public view returns (uint256) {
return counter * 2; // reading state
}
// Can call other view/pure functions
function combined() public view returns (uint256) {
return getCount() + 1;
}
// CANNOT:
// - write to state variables
// - emit events
// - call non-view functions
// - use selfdestruct
// - send Ether
// view functions can be called off-chain for free (eth_call)
}Funções Pure
Funções pure não podem ler nem escrever estado — só computam sobre suas entradas. São as mais restritas e as mais baratas de chamar off-chain. Use pure para funções utilitárias (matemática, hashing de entradas). Se você se pegar precisando de msg.sender ou dados de bloco, use view. pure só pode chamar outras funções pure.
contract PureFn {
// pure: cannot read OR write state
function add(uint256 a, uint256 b) public pure returns (uint256) {
return a + b;
}
function square(uint256 x) public pure returns (uint256) {
return x * x;
}
// pure can only use:
// - function parameters
// - local memory variables
// - other pure functions
function combined(uint256 x) public pure returns (uint256) {
uint256 y = square(x); // calling another pure fn
return add(y, 1);
}
// CANNOT read: state variables, msg.sender, block.timestamp, etc.
// CANNOT call view functions
}Funções Payable
Funções payable podem receber Ether via msg.value. O Ether é automaticamente somado ao saldo do contrato. Só funções payable e receive/fallback podem aceitar Ether. Sempre valide msg.value se você espera um valor específico. Funções não payable revertem se receberem Ether.
contract Payable {
address payable public owner;
constructor() {
owner = payable(msg.sender);
}
// payable: function can receive Ether
function deposit() public payable {
// msg.value is the amount of wei sent
// Ether is automatically added to contract balance
}
function getBalance() public view returns (uint256) {
return address(this).balance;
}
// Withdraw to owner
function withdraw() public {
require(msg.sender == owner, "not owner");
owner.transfer(address(this).balance);
}
// payable address (the contract itself can be paid)
receive() external payable {
// called when calldata is empty + value sent
}
}Valores de Retorno e Retornos Nomeados
Funções podem retornar múltiplos valores via tuplas. Retornos nomeados melhoram a legibilidade e permitem atribuir diretamente sem instrução return. Instruções return explícitas sobrescrevem os retornos nomeados. Use desestruturação (a, b) = f() para capturar múltiplos retornos; use (, b) ou (a,) para pular valores que não precisa.
contract Returns {
// Single return
function one() public pure returns (uint256) {
return 42;
}
// Multiple returns
function two() public pure returns (uint256, bool) {
return (1, true);
}
// Named returns — assign directly
function named() public pure returns (uint256 a, uint256 b) {
a = 1;
b = 2;
// no return keyword needed
}
// Mixed: explicit return overrides
function mixed(bool x) public pure returns (uint256 a, uint256 b) {
a = 1;
if (x) return (10, 20); // explicit return
b = 2;
}
// Destructuring assignment
function caller() public pure returns (uint256) {
(uint256 x, uint256 y) = two();
return x + y;
}
// Skip values with commas
function skip() public pure returns (bool) {
(, bool y) = two();
return y;
}
}Sobrecarga de Funções
Solidity suporta sobrecarga de funções: múltiplas funções com o mesmo nome, mas tipos ou contagem de parâmetros diferentes. O compilador resolve qual chamar com base nos tipos dos argumentos. Só o tipo de retorno não distingue sobrecargas. Sobrecargas são úteis para aceitar tanto address quanto address payable, ou faixas numéricas diferentes.
contract Overload {
// Same name, different parameter types/counts
function add(uint256 a, uint256 b) public pure returns (uint256) {
return a + b;
}
function add(uint256 a, uint256 b, uint256 c) public pure returns (uint256) {
return a + b + c;
}
function add(string memory a, string memory b)
public pure returns (string memory)
{
return string.concat(a, b);
}
// Caller selects which via argument types
function test() public pure returns (uint256, uint256, string memory) {
return (add(1, 2), add(1, 2, 3), add("a", "b"));
}
// NOTE: return type alone does NOT distinguish overloads
// function f() returns (uint256) and f() returns (bool) — INVALID
}Construtor e Funções Especiais
Construtor
constructor roda uma vez quando o contrato é implantado, para inicializar o estado. Não pode ser chamado de novo. Argumentos do construtor são acrescentados ao bytecode de implantação ou passados via ABI, dependendo do framework. Para herança, passe os argumentos do construtor pai na lista de herança (Owned(_owner)) ou no estilo modificador (A() B()).
contract Owned {
address public owner;
// constructor runs once at deployment
constructor(address _owner) {
owner = _owner;
}
modifier onlyOwner() {
require(msg.sender == owner, "not owner");
_;
}
function transferOwnership(address newOwner) public onlyOwner {
owner = newOwner;
}
}
// Inheritance: constructor args
contract Child is Owned {
constructor(address _owner) Owned(_owner) {}
}
// No constructor = default constructor (no args)
contract NoCtor {}
// Multiple inheritance: order matters
contract A { constructor() {} }
contract B { constructor() {} }
contract C is A, B {
constructor() A() B() {}
}Função Receive
receive() é invocada quando uma chamada sem calldata envia Ether (ex.: send/transfer para o contrato). Deve ser 'external payable', sem argumentos nem retornos. Só uma função receive é permitida. Se ausente e sem fallback, transferências simples de Ether revertem (exceto via selfdestruct, que pode forçar Ether).
contract Receiver {
event Received(address from, uint256 amount);
// receive: called on plain Ether transfers (no calldata)
// Must be 'external payable', no args, no returns
// Only ONE receive per contract
receive() external payable {
emit Received(msg.sender, msg.value);
}
// Triggered by: transfer(), send(), or empty calldata tx
// Use this to react to incoming Ether
function balance() public view returns (uint256) {
return address(this).balance;
}
}
// If no receive/fallback exists, the contract rejects plain Ether.
// Exception: contracts can be forced via selfdestruct (always).Função Fallback
fallback() é chamada quando nenhuma função casa com o seletor, ou quando receive está ausente e uma transferência simples de Ether é tentada. Pode ser payable. Mantenha a lógica do fallback mínima — quando invocada via send()/transfer(), só tem 2300 de gas (o estipêndio), que não cobre escritas de storage nem emissão de eventos.
contract Fallback {
event Log(string message, address from, uint256 value, bytes data);
// fallback: called when no function matches the calldata
// OR when receive is absent and calldata is empty
fallback() external payable {
emit Log("fallback", msg.sender, msg.value, msg.data);
}
// With calldata (function not found)
// Without calldata + no receive => fallback runs
// Modern: separate receive and fallback
// receive() external payable { ... } // empty calldata + value
// fallback() external payable { ... } // unknown function
// Make fallback cheap — it can run out of gas on send()/transfer() (2300 stipend)
function safeFallback() external {
// logic here must be < 2300 gas if called via transfer/send
}
}Selfdestruct
selfdestruct envia o Ether inteiro restante a um endereço especificado e (pré-Dencun) remove o código do contrato. Pós-EIP-6780 (março de 2024), só remove o código se chamada dentro da mesma transação de implantação — caso contrário, apenas transfere o Ether. Nunca confie em selfdestruct para segurança: Ether forçado ainda pode chegar, e o código pode persistir.
contract SelfDestruct {
address payable public owner;
constructor() { owner = payable(msg.sender); }
function destroy() public {
require(msg.sender == owner, "not owner");
// Sends all Ether to recipient, then deletes the contract
selfdestruct(payable(msg.sender));
}
}
// IMPORTANT WARNINGS:
// - After EIP-6780 (Dencun), selfdestruct no longer deletes code
// unless called in the same transaction that deployed the contract
// - It still sends all Ether to the recipient
// - The recipient could be a contract with no receive/fallback and
// it still gets the Ether (forced transfer)
// - Do NOT rely on selfdestruct for security; prefer a 'paused' flagSeletor de Função
Toda função tem um seletor de 4 bytes = primeiros 4 bytes de keccak256(assinatura). A assinatura é o nome da função e os tipos de parâmetros sem espaços, ex.: 'transfer(address,uint256)'. A EVM usa o seletor para rotear chamadas. msg.sig dá o seletor da função atual. abi.encodeWithSelector/Signature constroem calldata para chamadas de baixo nível.
contract Selector {
// First 4 bytes of keccak256 of the function signature
// signature = "functionName(paramType1,paramType2,...)"
bytes4 public constant SELECTOR =
bytes4(keccak256("transfer(address,uint256)"));
function getSelector() public pure returns (bytes4) {
return bytes4(keccak256("transfer(address,uint256)")));
// = 0xa9059cbb
}
function thisSelector() public pure returns (bytes4) {
return msg.sig; // selector of the currently running function
}
// Used for low-level calls
function callTransfer(address token, address to, uint256 amount)
public returns (bool, bytes memory)
{
(bool ok, bytes memory data) = token.call(
abi.encodeWithSelector(0xa9059cbb, to, amount)
);
return (ok, data);
}
// abi.encodeWithSignature uses the string form
function altCall(address token, address to, uint256 amount)
public returns (bool, bytes memory)
{
return token.call(
abi.encodeWithSignature("transfer(address,uint256)", to, amount)
);
}
}Modificadores
Básico de Modificadores
Modificadores envolvem funções com condições pré/pós reutilizáveis. O espaço reservado _; é onde o corpo da função executa. Modificadores são ótimos para controle de acesso (onlyOwner), validação (validInput) e proteções contra reentrância. São aplicados antes do corpo da função por padrão — use _; para controlar onde o corpo roda.
contract ModBasics {
address public owner;
uint256 public count;
constructor() { owner = msg.sender; }
// Define a modifier
modifier onlyOwner() {
require(msg.sender == owner, "not owner");
_; // placeholder for the function body
}
// Apply it
function increment() public onlyOwner {
count += 1;
}
function reset() public onlyOwner {
count = 0;
}
// Anyone can read
function getCount() public view returns (uint256) {
return count;
}
}Modificador com Argumentos
Modificadores podem receber argumentos, tornando-os flexíveis. Os argumentos são avaliados no ponto de chamada e vinculados quando o modificador roda. Padrões comuns: costs(price) para pagar-por-chamada, onlyRole(role) para RBAC, rateLimit(window) para estrangular. Lógica antes de _; é pré-condição, depois de _; é pós-condição.
contract ModArgs {
modifier costs(uint256 price) {
require(msg.value >= price, "insufficient payment");
_;
// optional: refund excess after function runs
if (msg.value > price) {
payable(msg.sender).transfer(msg.value - price);
}
}
modifier onlyAddress(address allowed) {
require(msg.sender == allowed, "not allowed");
_;
}
function buyItem() public payable costs(1 ether) {
// msg.value must be >= 1 ether to enter
// excess refunded after body runs
}
function adminOnly() public onlyAddress(0xAbC...) {
// restricted to a hardcoded address
}
}Múltiplos Modificadores
Uma função pode ter múltiplos modificadores. Eles executam em ordem, envolvendo o corpo da função como uma pilha: a pré-condição do primeiro modificador roda primeiro, depois a do segundo, ..., depois o corpo, e depois se desenrolam ao contrário. A ordem importa — ponha as checagens mais baratas/mais propensas a falhar primeiro, para economizar gas.
contract MultiMod {
address public owner;
bool public paused;
uint256 public value;
constructor() { owner = msg.sender; }
modifier onlyOwner() {
require(msg.sender == owner, "not owner");
_;
}
modifier whenNotPaused() {
require(!paused, "paused");
_;
}
modifier validValue(uint256 v) {
require(v > 0, "invalid value");
_;
}
// Multiple modifiers — executed in order
// Stack-like: A B body B' A'
function setValue(uint256 v)
public
onlyOwner // 1. check owner
whenNotPaused // 2. check not paused
validValue(v) // 3. validate input
{
value = v;
}
}Ordem de Modificadores e Gas
A ordem dos modificadores afeta gas e clareza. Ponha checagens baratas primeiro (booleanos, comparações de endereço) e caras por último (escritas de storage, chamadas externas). Também ponha primeiro as checagens mais propensas a falhar — isso curto-circuita e devolve o gas não usado. Documente a ordem pretendida com comentários.
contract ModOrder {
// Order modifiers from cheapest to most expensive
// OR most likely to fail first (to short-circuit)
modifier onlyOwner() { require(msg.sender == owner, "1"); _; }
modifier nonZero(uint256 x) { require(x != 0, "2"); _; }
modifier withinRange(uint256 x) {
require(x >= 1 && x <= 100, "3");
_;
}
modifier notPaused() { require(!paused, "4"); _; }
// Good order: cheap + likely-to-fail first
function good(uint256 x)
public
notPaused // 1. cheap bool check
onlyOwner // 2. address compare
nonZero(x) // 3. cheap input check
withinRange(x) // 4. more complex range check
{}
address public owner;
bool public paused;
constructor() { owner = msg.sender; }
}Padrões Comuns de Modificadores
Padrões comuns de modificadores: nonReentrant (defina uma trava antes do corpo, libere depois), whenNotPaused/whenPaused (disjuntor), onlyRole (RBAC com papéis bytes32), rateLimit (estrangulamento por usuário usando timestamps). A proteção contra reentrância é a mais importante — aplique-a a qualquer função que faça uma chamada externa após mudança de estado.
contract Patterns {
// 1. Reentrancy guard
uint256 private _status = 1;
modifier nonReentrant() {
require(_status == 1, "reentrant");
_status = 2;
_;
_status = 1;
}
// 2. Pausable
bool public paused;
modifier whenNotPaused() {
require(!paused, "paused");
_;
}
modifier whenPaused() {
require(paused, "not paused");
_;
}
// 3. Role-based
mapping(bytes32 => bool) public hasRole;
modifier onlyRole(bytes32 role) {
require(hasRole[role], "missing role");
_;
}
// 4. Rate limit (basic)
mapping(address => uint256) public lastCall;
modifier rateLimit() {
require(block.timestamp >= lastCall[msg.sender] + 1 minutes, "rate");
lastCall[msg.sender] = block.timestamp;
_;
}
}Eventos
Declaração e Emit de Eventos
Eventos são registrados na blockchain e legíveis por clientes off-chain (via eth_getLogs). NÃO são legíveis por outros contratos. Use indexed em até 3 parâmetros para torná-los filtráveis. Eventos custam menos gas que escritas de storage. Sempre emita eventos para mudanças importantes de estado, para que dApps e indexadores possam reagir.
contract Events {
// Declare event (outside functions, can be at file level)
event Transfer(address indexed from, address indexed to, uint256 value);
event Approval(address indexed owner, address indexed spender, uint256 value);
mapping(address => uint256) public balances;
function transfer(address to, uint256 amount) public returns (bool) {
require(balances[msg.sender] >= amount, "insufficient");
balances[msg.sender] -= amount;
balances[to] += amount;
// Emit the event
emit Transfer(msg.sender, to, amount);
return true;
}
function approve(address spender, uint256 amount) public returns (bool) {
emit Approval(msg.sender, spender, amount);
return true;
}
}Parâmetros Indexados
Parâmetros indexed viram topics que clientes off-chain (dApps, The Graph, indexadores) podem filtrar. Máximo de 3 parâmetros indexed por evento (o 4º topic é reservado para o hash da assinatura do evento). Tipos de valor indexed (uint, address) são guardados diretamente; tipos de referência indexed (string, bytes, arrays) são hasheados com keccak256 e irrecuperáveis.
contract Indexed {
// Up to 3 indexed params (in non-anonymous events)
// Indexed params become 'topics' that clients can filter on
event OrderPlaced(
address indexed buyer, // topic 1
address indexed token, // topic 2
uint256 indexed orderId, // topic 3
uint256 amount, // data (not filterable)
uint256 price // data
);
function placeOrder(address token, uint256 amount, uint256 price)
public returns (uint256 id)
{
id = uint256(keccak256(abi.encodePacked(msg.sender, block.number)));
emit OrderPlaced(msg.sender, token, id, amount, price);
}
// Clients can filter:
// eth_getLogs({topics: [sig, buyerAddr, tokenAddr, orderId]})
//
// Indexed arrays/strings/bytes are hashed (keccak256) —
// you can't recover the original value, only compare hashes.
}Eventos Anônimos
Eventos anonymous pulam o hash da assinatura do evento em topic[0], liberando um slot — então você ganha 4 parâmetros indexed em vez de 3. A troca: clientes não podem filtrar pelo nome do evento (assinatura), tornando mais difícil distinguir múltiplos eventos anônimos num contrato. Raramente útil; a economia de gas é minúscula.
contract Anonymous {
// anonymous: skips storing the event signature as topic[0]
// So you can have up to 4 indexed params instead of 3
event Log(
address indexed from,
address indexed to,
uint256 indexed amount,
uint256 indexed timestamp, // 4th indexed (only with anonymous)
bytes data
) anonymous;
function log() public {
emit Log(msg.sender, address(0), 100, block.timestamp, "");
}
// Trade-offs:
// + 1 more indexed param allowed
// - Clients cannot filter by event signature
// - Harder to distinguish multiple anonymous events
// - Slightly cheaper gas
// Rarely used; prefer named events for clarity.
}Boas Práticas de Eventos
Boas práticas: emita depois das mudanças de estado (para que o evento reflita o estado final), inclua campos que ajudem indexadores a evitar chamadas RPC extras (como newBalance), evite emitir em loops apertados (agrupe em lote em vez disso) e indexe os campos mais frequentemente filtrados (endereços, IDs, códigos de status). Eventos são o canal primário de comunicação contrato-para-off-chain.
contract EventBest {
// 1. Name events with past tense or noun: Transfer, Deposit, OrderPlaced
event Transfer(address indexed from, address indexed to, uint256 value);
// 2. Emit AFTER state changes succeed
mapping(address => uint256) public balances;
function transfer(address to, uint256 amt) public {
balances[msg.sender] -= amt; // state first
balances[to] += amt;
emit Transfer(msg.sender, to, amt); // event after
}
// 3. Include enough data to reconstruct state
event Deposit(
address indexed account,
uint256 amount,
uint256 newBalance, // helps indexers avoid extra reads
uint256 timestamp
);
// 4. Don't emit in a loop — batch instead
event BatchTransfer(address[] to, uint256[] amounts);
function batch(address[] memory to, uint256[] memory amounts) public {
emit BatchTransfer(to, amounts); // one event, not N
}
// 5. Index the fields users filter on (addresses, IDs)
}Eventos vs Logs vs Storage
Storage está na trie de estado — legível por outros contratos e funções view, mas caro (~20k gas por SSTORE). Eventos/logs estão na trie de recibos — NÃO legíveis por contratos, mas baratos (~1-2k gas) e acessíveis off-chain via eth_getLogs. Use storage para decisões on-chain, eventos para comunicar mudanças de estado a dApps e indexadores.
contract Compare {
// Storage: persistent, readable by contracts, expensive
uint256 public storedValue; // SSTORE costs ~20k gas
// Events (logs): persistent-ish, NOT readable by contracts, cheap
event ValueChanged(uint256 oldValue, uint256 newValue);
function set(uint256 newValue) public {
uint256 old = storedValue;
storedValue = newValue; // SSTORE (~20k gas)
emit ValueChanged(old, newValue); // LOG (~1-2k gas)
}
// Logs live in the block's receipt trie, NOT the state trie.
// They are NOT accessible from other contracts.
// function readLog() public view returns (...) {
// CANNOT access emitted events
// }
// Off-chain tools (dApps, The Graph) read logs via eth_getLogs.
// Use storage for on-chain logic; events for off-chain observers.
}Tratamento de Erros
Require
require(cond, msg) reverte a transação e devolve o gas não usado se cond for falsa. É a primitiva de validação mais comum — use para checagens de entrada, controle de acesso e pré-condições. A string de mensagem custa gas (guardada no bytecode implantado). Para economizar gas, use erros personalizados (revert NomeErro()) em vez de mensagens de string.
contract Require {
mapping(address => uint256) public balances;
function deposit() public payable {
require(msg.value > 0, "must send ether");
balances[msg.sender] += msg.value;
}
function withdraw(uint256 amount) public {
// require(condition, message)
// Reverts with the message if condition is false
// Refunds all unused gas to the caller (post-0.8.0 with custom errors, also refunds)
require(balances[msg.sender] >= amount, "insufficient balance");
balances[msg.sender] -= amount;
payable(msg.sender).transfer(amount);
}
// Pre-0.8.0: require with no message was cheaper
// 0.8.4+: prefer custom errors (cheaper, see other item)
function cheap(uint256 x) public pure {
if (x == 0) revert ZeroValue(); // custom error
}
error ZeroValue();
}Revert
revert(msg) reverte explicitamente a transação com uma string de motivo. Use revert() dentro de if quando precisar de lógica ramificada (require é só açúcar sintático). revert() sem mensagem é mais barato que revert("msg"). Erros personalizados (revert NomeErro(args)) são os mais baratos e mais descritivos — prefira-os em código novo.
contract Revert {
function explicit(uint256 x) public pure {
if (x == 0) {
revert("zero not allowed"); // explicit revert with message
}
if (x > 100) {
revert("too big"); // can place anywhere
}
}
// revert() with no message (cheapest string revert)
function silent(uint256 x) public pure {
if (x == 0) revert(); // no reason
}
// Custom error (0.8.4+) — recommended
error TooBig(uint256 given, uint256 max);
function custom(uint256 x) public pure {
if (x > 100) revert TooBig(x, 100);
}
// Inside an internal function, revert propagates up
function caller(uint256 x) public pure {
inner(x); // reverts here if x is bad
}
function inner(uint256 x) internal pure {
if (x == 0) revert("zero");
}
}Assert
assert(cond) é para invariantes que nunca deveriam ser falsas se o código estiver correto — um assert falhado indica um bug. Pré-0.8.0, assert consumia o gas inteiro; desde a 0.8.0 ele se comporta como revert. Use require para validação de entrada e condições de erro esperadas; use assert só para estados impossíveis que sinalizam bug. As checagens automáticas de overflow modernas usam revert, não assert.
contract Assert {
function check(uint256 x) public pure returns (uint256) {
uint256 result = x + 1;
// assert: for invariants that should NEVER be false
// If it fails, something is critically broken.
assert(result > x); // overflow check (auto in 0.8+)
return result;
}
// Pre-0.8.0: assert was used for overflow checks (used all gas)
// Post-0.8.0: arithmetic auto-checks use revert, not assert
//
// Modern guidance:
// - Use require/revert for input validation & expected failures
// - Use assert ONLY for invariants that indicate a code bug
// (something that should be impossible if the code is correct)
//
// Example: a state machine that should never reach an invalid state
enum State { Created, Paid, Shipped }
State public state;
function ship() public {
require(state == State.Paid, "not paid");
state = State.Shipped;
assert(state == State.Shipped); // invariant
}
}Erros Personalizados
Erros personalizados (0.8.4+) são a forma recomendada de reverter. Codificam-se como um seletor de 4 bytes mais argumentos codificados em ABI — muito mais barato que mensagens de string (guardadas como UTF-8 completo no bytecode). Clientes decodificam o seletor para saber qual erro ocorreu e ler os argumentos estruturados. Defina erros no nível do arquivo ou do contrato, depois 'revert NomeErro(args);'.
contract CustomError {
// Define errors (outside functions, can be at file level)
error InsufficientBalance(uint256 available, uint256 required);
error Unauthorized(address caller);
error TransferFailed(address from, address to);
mapping(address => uint256) public balances;
function withdraw(uint256 amount) public {
if (balances[msg.sender] < amount) {
// Cheaper than require(..., "insufficient balance")
revert InsufficientBalance(balances[msg.sender], amount);
}
balances[msg.sender] -= amount;
(bool ok, ) = msg.sender.call{value: amount}("");
if (!ok) revert TransferFailed(address(this), msg.sender);
}
function adminOnly() public {
if (msg.sender != address(0x123)) {
revert Unauthorized(msg.sender);
}
}
// Why cheaper? The error selector (4 bytes) replaces a long string,
// saving bytecode size and gas per call.
// ABI decodes arguments so clients get structured data.
}Try / Catch
try/catch trata erros só de chamadas externas — não consegue capturar reverts de chamadas de função internas. A cláusula 'returns' captura o valor de sucesso. catch Error() captura revert/require com mensagens de string; catch Panic() captura panics de assert/overflow; catch (bytes) é um fallback para erros personalizados e reverts desconhecidos. Use para tratar graciosamente falhas de contratos externos.
contract TryCatch {
interface IToken {
function transfer(address to, uint256 amount) external returns (bool);
}
IToken public token;
constructor(address _token) { token = IToken(_token); }
function safeTransfer(address to, uint256 amount)
public returns (bool success, bool tokenOk)
{
try token.transfer(to, amount) returns (bool ok) {
// Called if no revert; 'ok' captures the return value
return (ok, true);
} catch Error(string memory reason) {
// revert("reason") or require(_, "reason")
// log reason
return (false, false);
} catch Panic(uint256 code) {
// assert failures (code 0x01) or overflow (0x11)
return (false, false);
} catch (bytes memory lowLevelData) {
// Any other revert (including custom errors)
return (false, false);
}
}
// try/catch ONLY works with EXTERNAL calls (or this.f()).
// It does NOT catch errors in internal calls.
// The called function MUST return something (not void).
}Mensagens e Padrões de Erro
O tratamento de erros moderno usa erros personalizados para reverts estruturados e baratos. Mensagens antigas de string ainda são comuns em código pré-0.8.4. Sempre inclua contexto acionável: qual valor estava errado, o que era esperado. Evite por endereços/números dinâmicos em mensagens de string — inflam o bytecode e não são analisáveis. Use mensagens prefixadas ('INVALIDO:') se precisar de strings, para ajudar a indexação de logs.
contract Errors {
// 1. Custom errors (best for new code)
error InvalidAmount(uint256 given);
error NotOwner(address caller, address owner);
// 2. String errors (older style)
function old(uint256 x) public pure {
require(x > 0, "INVALID: must be > 0"); // prefix helps indexing
require(x < 100, "INVALID: must be < 100");
}
// 3. Custom error with structured data
function newStyle(uint256 x) public pure {
if (x == 0) revert InvalidAmount(x);
}
// 4. Error with multiple fields
address public owner;
constructor() { owner = msg.sender; }
function guarded() public view {
if (msg.sender != owner) {
revert NotOwner(msg.sender, owner);
}
}
// 5. Don't put dynamic data in string errors (expensive & unparseable)
// BAD: require(msg.sender == owner, "not owner: caller 0x123...");
// GOOD: revert NotOwner(msg.sender, owner);
}Herança
Herança com 'is'
A herança usa a palavra-chave 'is'. Um contrato filho herda todas as variáveis de estado, funções e modificadores do pai. Argumentos do construtor pai são passados na lista de herança (Animal("cachorro")) ou pelo estilo modificador do construtor. Um filho pode sobrescrever funções marcadas virtual no pai. Solidity suporta herança múltipla (linearização via C3).
contract Animal {
string public species;
constructor(string memory _species) {
species = _species;
}
function speak() public virtual returns (string memory) {
return "...";
}
}
contract Dog is Animal {
constructor() Animal("dog") {}
// Override parent function
function speak() public override returns (string memory) {
return "Woof";
}
}
// Multiple inheritance
contract Puppy is Dog {
function speak() public override returns (string memory) {
return "Yip";
}
}Virtual e Override
virtual marca uma função como sobrescrevível; override marca uma função como sobrescrevendo seu pai. Funções são não-virtuais por padrão (mais seguro). Ao sobrescrever de múltiplos pais que compartilham uma base, liste-os: override(A, B). Para permitir mais sobrescritas, use virtual override. Variáveis de estado não podem ser sobrescritas (só sombreadas em memória).
contract Base {
function f() public pure virtual returns (string memory) {
return "base";
}
function g() public pure virtual returns (string memory) {
return "base-g";
}
}
contract Middle is Base {
// Override a single parent
function f() public pure override returns (string memory) {
return "middle";
}
}
contract Multi is Base {
// Override (also virtual so children can override again)
function g() public pure virtual override returns (string memory) {
return "multi";
}
}
contract Combined is Middle, Multi {
// Override multiple parents (explicit list)
function f() public pure override(Middle, Base) returns (string memory) {
return "combined";
}
function g() public pure override(Multi, Base) returns (string memory) {
return "combined-g";
}
}Palavra-chave Super
super.method() chama a versão do pai, permitindo estender em vez de substituir o comportamento. Com herança simples é intuitivo. Com herança múltipla, super segue a linearização C3 — pode chamar um contrato irmão, não o pai lexical. Sempre confira a ordem de linearização (o mais derivado por último) ao usar super em herança em diamante.
contract A {
function label() public pure virtual returns (string memory) {
return "A";
}
}
contract B is A {
function label() public pure virtual override returns (string memory) {
return string.concat("B>", super.label()); // calls A.label()
}
}
contract C is B {
function label() public pure override returns (string memory) {
return string.concat("C>", super.label()); // calls B.label()
}
}
// super refers to the NEXT contract in the linearization,
// not necessarily the lexical parent. With multiple inheritance,
// super.label() may call a sibling.
contract P1 { function f() public pure virtual returns (uint) { return 1; } }
contract P2 { function f() public pure virtual returns (uint) { return 2; } }
contract Child is P1, P2 {
function f() public pure override(P1, P2) returns (uint) {
return super.f(); // calls P2.f() (last in linearization)
}
}Herança Múltipla
Solidity suporta herança múltipla via a palavra-chave 'is'. Liste os pais do mais base ao mais derivado: 'is Ownable, Pausable'. O algoritmo de linearização C3 produz uma ordem determinística, resolvendo o problema do diamante. Use 'override(A, B)' ao sobrescrever uma função herdada de múltiplos pais. Construtores rodam em ordem de linearização (pais primeiro).
contract Ownable {
address public owner;
constructor() { owner = msg.sender; }
modifier onlyOwner() { require(msg.sender == owner); _; }
}
contract Pausable {
bool public paused;
modifier whenNotPaused() { require(!paused); _; }
}
// Multiple inheritance: list parents from most base to most derived
contract Token is Ownable, Pausable {
mapping(address => uint256) public balances;
function mint(address to, uint256 amount)
public
onlyOwner // from Ownable
whenNotPaused // from Pausable
{
balances[to] += amount;
}
}
// C3 Linearization order (for 'Token'):
// Token -> Pausable -> Ownable -> (object)
// Determined by the order in 'is' list (left to right, base first)
//
// Diamond problem is resolved by C3 — there is a single
// deterministic order, no ambiguity. But you must understand it
// when using super.Herança de Construtores
Argumentos do construtor pai podem ser passados na lista de herança (A(42)) para valores fixos, ou no construtor filho via sintaxe de modificador (A(_a)) para valores de runtime. Com múltiplos pais, passe-os em ordem de linearização (o mais base primeiro). Se um pai tem construtor sem argumentos, você pode omiti-lo. Construtores rodam uma vez na implantação, em ordem de linearização.
contract A {
uint256 public a;
constructor(uint256 _a) { a = _a; }
}
// Style 1: pass args in inheritance list
contract B1 is A(42) {
// 'a' is set to 42 at deployment
}
// Style 2: pass via modifier-style in child constructor
contract B2 is A {
constructor(uint256 _b) A(_b * 2) {
// 'a' is set to _b * 2
}
}
// Style 3: child has its own constructor + parent args
contract B3 is A {
uint256 public b;
constructor(uint256 _a, uint256 _b) A(_a) {
b = _b;
}
}
// With multiple parents, order = linearization order
contract C1 { constructor(uint) {} }
contract C2 { constructor(uint) {} }
contract C3 is C1, C2 {
constructor(uint x) C1(x) C2(x+1) {}
}Contratos Abstratos e Interfaces
Contratos Abstratos
Um contrato abstrato tem pelo menos uma função sem corpo (declarada com virtual, sem implementação). Não pode ser implantado diretamente — um filho precisa implementar todas as funções abstratas. Use contratos abstratos quando quiser estado compartilhado + modificadores + implementação parcial. A palavra-chave 'abstract' é obrigatória antes da 0.6.0 se qualquer função não tiver corpo.
abstract contract Ownable {
address public owner;
constructor() { owner = msg.sender; }
modifier onlyOwner() {
require(msg.sender == owner, "not owner");
_;
}
// abstract function — no body, must be implemented by children
function sensitiveAction() public virtual;
// Can have implemented functions too
function transferOwnership(address newOwner) public onlyOwner {
owner = newOwner;
}
}
contract Vault is Ownable {
function sensitiveAction() public override onlyOwner {
// implementation here
}
}Interfaces
Interfaces são como contratos puramente abstratos: sem estado, sem construtores, sem funções implementadas, todas as funções external. Elas definem a ABI de um contrato para interagir com implementações desconhecidas. Use interfaces para chamar outros contratos sem herdar lógica. Nomeie-as com prefixo 'I' (IERC20, IUniswapV2Pair). Funções em interfaces não podem ter modificadores além de external view/payable.
interface IERC20 {
// Functions only — no implementation, no state, no constructor
function totalSupply() external view returns (uint256);
function balanceOf(address account) external view returns (uint256);
function transfer(address to, uint256 amount) external returns (bool);
function approve(address spender, uint256 amount) external returns (bool);
function allowance(address owner, address spender)
external view returns (uint256);
function transferFrom(address from, address to, uint256 amount)
external returns (bool);
event Transfer(address indexed from, address indexed to, uint256 value);
event Approval(address indexed owner, address indexed spender, uint256 value);
}
contract MyToken is IERC20 {
// Must implement ALL functions declared in the interface
mapping(address => uint256) private _balances;
uint256 private _totalSupply;
function totalSupply() external view returns (uint256) {
return _totalSupply;
}
// ... implement the rest
}Virtual vs Abstract
abstract = ao menos uma função sem corpo; o contrato não pode ser implantado. virtual = uma função com corpo que filhos PODEM sobrescrever. Uma função pode ser ambas (virtual + sem corpo). Interfaces são implicitamente totalmente abstratas — toda função é virtual, sem corpo e external. Use abstract para lógica compartilhada, interfaces para definições puras de ABI.
// ABSTRACT contract: has at least one unimplemented function
// Must declare 'abstract'; cannot be deployed directly
abstract contract Counter {
uint256 public count;
function increment() public virtual; // no body -> abstract
function reset() public {
count = 0;
}
}
// VIRTUAL: function HAS a body, but CAN be overridden
contract Base {
function f() public pure virtual returns (uint) {
return 1;
}
}
contract Child is Base {
function f() public pure override returns (uint) {
return 2;
}
}
// A function can be both virtual and abstract (no body)
abstract contract A {
function f() public pure virtual; // virtual + no body
}
// Interfaces are implicitly abstract — all functions virtual+abstract
interface I {
function f() external; // implicit virtual, no body
}Boas Práticas de Interfaces
Boas práticas de interfaces: prefixe com 'I', mantenha-as mínimas (só o que os chamadores precisam), todas as funções external, sem estado/construtores/implementação, eventos permitidos. Use interfaces para: (1) chamar outros contratos cujo fonte você não tem, (2) definir padrões (IERC20, IERC721), (3) reduzir bytecode por não herdar implementação. Implementar uma interface força seu contrato a satisfazer o padrão.
// 1. Name with 'I' prefix
interface IERC721 {
function ownerOf(uint256 tokenId) external view returns (address);
function transferFrom(address from, address to, uint256 tokenId) external;
}
// 2. Keep minimal — only what callers need
interface IPriceFeed {
function latestAnswer() external view returns (int256);
function decimals() external view returns (uint8);
}
// 3. All functions external (required)
// 4. No state variables, no constructors, no implemented functions
// 5. Events ARE allowed in interfaces
interface IEvents {
event SomethingHappened(uint256 indexed id);
}
// 6. Use to call contracts you don't have source for
contract Consumer {
IPriceFeed public feed;
constructor(address _feed) { feed = IPriceFeed(_feed); }
function price() public view returns (int256) {
return feed.latestAnswer();
}
}
// 7. Implement to satisfy a standard (ERC20, ERC721)
contract MyToken is IERC20 { /* ... */ }Exemplo IERC20 (Interface)
IERC20 define o padrão de token fungível ERC-20. A interface declara as 6 funções obrigatórias (totalSupply, balanceOf, transfer, approve, allowance, transferFrom) mais os metadados opcionais (name, symbol, decimals) e 2 eventos. Qualquer contrato que implemente essa interface pode ser tratado como token ERC-20. Use a interface para interagir com qualquer ERC-20 sem conhecer sua implementação interna.
// Canonical ERC-20 interface
interface IERC20 {
event Transfer(address indexed from, address indexed to, uint256 value);
event Approval(address indexed owner, address indexed spender, uint256 value);
function name() external view returns (string memory);
function symbol() external view returns (string memory);
function decimals() external view returns (uint8);
function totalSupply() external view returns (uint256);
function balanceOf(address account) external view returns (uint256);
function transfer(address to, uint256 amount) external returns (bool);
function allowance(address owner, address spender)
external view returns (uint256);
function approve(address spender, uint256 amount) external returns (bool);
function transferFrom(address from, address to, uint256 amount)
external returns (bool);
}
// Minimal interaction using the interface
contract Wallet {
IERC20 public token;
constructor(address _token) { token = IERC20(_token); }
function balance() public view returns (uint256) {
return token.balanceOf(address(this));
}
function send(address to, uint256 amount) public returns (bool) {
return token.transfer(to, amount);
}
}Bibliotecas
Básico de Bibliotecas
Bibliotecas são como contratos, mas não podem ter estado, herdar nem ser herdadas. São implantadas uma vez e reutilizadas via DELEGATECALL (external) ou embutidas (internal). Funções de biblioteca internal são embutidas no contrato chamador — sem implantação separada. Use bibliotecas para agrupar funções reutilizáveis (matemática, validação, formatação). A diretiva 'using SafeMath for uint256' permite chamar funções como a.b().
library SafeMath {
function add(uint256 a, uint256 b) internal pure returns (uint256) {
uint256 c = a + b;
require(c >= a, "overflow");
return c;
}
function sub(uint256 a, uint256 b) internal pure returns (uint256) {
require(b <= a, "underflow");
return a - b;
}
function mul(uint256 a, uint256 b) internal pure returns (uint256) {
if (a == 0) return 0;
uint256 c = a * b;
require(c / a == b, "overflow");
return c;
}
// Libraries CANNOT have state variables
// Libraries CANNOT inherit or be inherited
// All functions must be internal or external
// No constructor, no fallback, no receive
}
contract UsingSafeMath {
using SafeMath for uint256;
function calc(uint256 a, uint256 b) public pure returns (uint256) {
return a.add(b).mul(2); // a.add(b) calls SafeMath.add(a, b)
}
}Using For
'using Library for Type' anexa as funções da biblioteca àquele tipo, para que você possa chamar value.method() em vez de Library.method(value). O primeiro parâmetro da função da biblioteca deve casar com o tipo. Você também pode usar a diretiva no nível do arquivo (0.8.13+) com 'using {fn1, fn2} for Type;'. Isso é puramente açúcar sintático — o compilador reescreve para chamadas diretas.
library Strings {
function toString(uint256 value) internal pure returns (string memory) {
// convert uint to decimal string
if (value == 0) return "0";
uint256 temp = value;
uint256 digits;
while (temp != 0) { digits++; temp /= 10; }
bytes memory buffer = new bytes(digits);
while (value != 0) {
digits -= 1;
buffer[digits] = bytes1(uint8(48 + value % 10));
value /= 10;
}
return string(buffer);
}
}
contract UsingExample {
// Attach library functions to a type
using Strings for uint256;
function describe(uint256 x) public pure returns (string memory) {
// x.toString() calls Strings.toString(x)
return string.concat("Value: ", x.toString());
}
// Attach to a specific type globally (Solidity 0.8.13+)
// using {toString} for uint256; // file-level
// using SafeMath for uint256;
// using SafeMath for *; // not allowed
}Bibliotecas Internas
Funções de biblioteca internal são embutidas no bytecode do contrato chamador em tempo de compilação — não há DELEGATECALL em runtime, sem implantação de biblioteca, sem custo de chamada. Isso as torna essencialmente gratuitas de chamar (só o gas das operações em si). Use bibliotecas internas para helpers pure/view (matemática, conversão de string). O tamanho do bytecode do chamador cresce, mas o gas de chamada é menor que bibliotecas externas.
library Math {
// internal functions are INLINED into the caller's bytecode
// No separate deployment needed — saves gas on each call
function max(uint256 a, uint256 b) internal pure returns (uint256) {
return a > b ? a : b;
}
function min(uint256 a, uint256 b) internal pure returns (uint256) {
return a < b ? a : b;
}
function average(uint256 a, uint256 b)
internal pure returns (uint256)
{
// (a + b) / 2 can overflow; this avoids it
return (a & b) + ((a ^ b) / 2);
}
}
contract Calc {
using Math for uint256;
function doMath(uint256 x, uint256 y)
public pure returns (uint256, uint256, uint256)
{
return (x.max(y), x.min(y), x.average(y));
}
}
// Internal libraries are like helper functions that don't add
// runtime call overhead. Good for: math, validation, conversions.Bibliotecas Externas (Implantadas)
Funções de biblioteca external são implantadas como um contrato separado e chamadas via DELEGATECALL — rodam no contexto do chamador (storage, msg.sender). Útil para código utilitário compartilhado por muitos contratos (economiza gas total de implantação). Trocas: custo de DELEGATECALL por chamada (~1400 gas) e a biblioteca precisa ser implantada e seu endereço vinculado em tempo de compilação. A maioria das bibliotecas usa funções internas; externas são raras.
library BigMath {
// external functions => library is DEPLOYED as a separate contract
// Calls use DELEGATECALL — runs in caller's context (storage/msg)
function complexOperation(uint256[] storage arr)
external view returns (uint256 sum)
{
for (uint256 i = 0; i < arr.length; i++) {
sum += arr[i];
}
}
}
contract UsesExternal {
uint256[] public data;
using BigMath for uint256[];
function total() public view returns (uint256) {
return data.complexOperation(); // DELEGATECALL to BigMath
}
}
// External library trade-offs:
// + Shared bytecode: many contracts use one deployed library (saves deployment gas)
// + Caller bytecode stays small
// - DELEGATECALL overhead per call (~1400 gas)
// - Library must be deployed first and its address linked at compile time
//
// Most libraries are internal; external is rare (e.g., Create2BeaconProxy).Exemplo SafeMath (Pré-0.8.0)
SafeMath era a biblioteca canônica de checagem de overflow pré-0.8.0. Desde a 0.8.0, a aritmética reverte automaticamente em overflow, tornando SafeMath desnecessária para matemática básica. Ainda é útil para: (1) ler código legado, (2) embrulhar operações unchecked explicitamente, (3) o padrão de 'require pós-condição' como exemplo didático. A versão da OpenZeppelin continua amplamente referenciada.
// Before 0.8.0, arithmetic did NOT auto-check overflow.
// SafeMath was essential. Now it's mostly historical,
// but the pattern is instructive and still useful for
// explicit intent.
library SafeMath {
function add(uint256 a, uint256 b) internal pure returns (uint256) {
uint256 c = a + b;
require(c >= a, "SafeMath: addition overflow");
return c;
}
function sub(uint256 a, uint256 b) internal pure returns (uint256) {
return sub(a, b, "SafeMath: subtraction overflow");
}
function sub(uint256 a, uint256 b, string memory errorMessage)
internal pure returns (uint256)
{
require(b <= a, errorMessage);
return a - b;
}
function mul(uint256 a, uint256 b) internal pure returns (uint256) {
if (a == 0) return 0;
uint256 c = a * b;
require(c / a == b, "SafeMath: multiplication overflow");
return c;
}
function div(uint256 a, uint256 b) internal pure returns (uint256) {
return div(a, b, "SafeMath: division by zero");
}
function div(uint256 a, uint256 b, string memory errorMessage)
internal pure returns (uint256)
{
require(b > 0, errorMessage);
return a / b;
}
}Transferências de Ether
Payable e msg.value
Funções payable aceitam Ether via msg.value (em wei). O Ether é automaticamente somado ao saldo do contrato — não precisa acompanhar manualmente, a menos que queira contabilidade por usuário. Valide msg.value para pagamentos exatos ou mínimos. Sempre devolva o excesso de Ether para não travá-lo no contrato. 1 ether = 10^18 wei.
contract PayableContract {
address payable public owner;
constructor() {
owner = payable(msg.sender);
}
// payable = function accepts Ether
function deposit() public payable {
// msg.value = wei sent with this call
// Ether auto-added to address(this).balance
// No need to update a balance variable here
}
function getBalance() public view returns (uint256) {
return address(this).balance;
}
// Specify required payment
function buyItem() public payable {
require(msg.value == 1 ether, "must pay 1 ether");
// process purchase
}
// Send excess back
function refundExcess(uint256 price) public payable {
uint256 excess = msg.value - price;
if (excess > 0) {
(bool ok, ) = msg.sender.call{value: excess}("");
require(ok, "refund failed");
}
}
}Transfer
address.transfer(quantia) envia Ether e reverte em falha. Encaminha um estipêndio fixo de 2300 gas, que historicamente prevenia reentrância, mas hoje é considerado frágil (custos de gas mudaram em Istambul 2019). Orientação moderna: use transfer só ao enviar a um endereço confiável (como o owner). Para destinatários arbitrários, use .call{value:} com proteções explícitas de reentrância, já que o estipêndio de 2300 pode ser insuficiente para lógica legítima de receive/fallback.
contract TransferExample {
address payable public recipient = payable(0xAbC...);
function sendViaTransfer() public payable {
// transfer: throws on failure, forwards 2300 gas stipend
// Simple and safe against reentrancy (limited gas)
recipient.transfer(1 ether);
}
function sendFromContract() public {
// address(this).balance = current contract balance
recipient.transfer(address(this).balance);
}
// Characteristics:
// - Reverts if recipient's receive/fallback uses > 2300 gas
// - 2300 gas stipend: enough for an event log, not a storage write
// - Safer than send (which returns false on failure)
// - But BEWARE: post-Istanbul (2019), some operations cost more,
// breaking contracts that relied on 2300 gas. Prefer .call{}.
}
// transfer is DEPRECATED for pushing to arbitrary addresses.
// Use .call{value:} and handle the return value.Send
address.send(quantia) retorna um booleano (true em sucesso, false em falha) — NÃO reverte automaticamente. Você DEVE verificar o valor de retorno e reverter em falha. Como transfer, encaminha só 2300 gas. send é propenso a erros (desenvolvedores esquecem de checar o retorno) e raramente usado em código moderno. Prefira .call{value:} para contratos novos.
contract SendExample {
address payable public recipient = payable(0xAbC...);
function sendViaSend() public payable returns (bool) {
// send: returns false on failure (does NOT revert)
// Also forwards 2300 gas stipend like transfer
bool success = recipient.send(1 ether);
require(success, "send failed"); // you MUST check the return value
return success;
}
// Common bug: forgetting to check the return value
function buggy() public payable {
recipient.send(1 ether); // BUG: silently fails
// state already updated => funds lost
}
// Correct: check + revert
function correct() public payable {
bool ok = recipient.send(1 ether);
require(ok, "send failed");
}
}
// send is rarely used in modern code.
// Prefer .call{value:} which gives more control + return data.Call (Recomendado)
.call{value: x}(...) é a forma recomendada de enviar Ether desde a 0.8.0. Encaminha a totalidade do gas disponível (sujeito à regra 63/64), então destinatários podem fazer lógica complexa. Retorna (bool, bytes) — você DEVE verificar o booleano e reverter em falha. Como encaminha a totalidade do gas, é vulnerável à reentrância — sempre pareie com um modificador nonReentrant ou siga checks-effects-interactions. Use call para destinatários arbitrários; transfer só para endereços confiáveis.
contract CallExample {
address payable public recipient = payable(0xAbC...);
function sendViaCall() public payable returns (bool) {
// .call returns (bool success, bytes memory data)
// Forwards ALL gas (63/64 rule), so recipient can do more
(bool success, ) = recipient.call{value: 1 ether}("");
require(success, "call failed");
return success;
}
// With calldata (call a function while sending Ether)
function callWithFunction(address token, address to, uint256 amount)
public returns (bool, bytes memory)
{
(bool ok, bytes memory data) = token.call{value: 0}(
abi.encodeWithSignature("transfer(address,uint256)", to, amount)
);
return (ok, data);
}
// Forward gas explicitly
function withGas() public returns (bool) {
(bool ok, ) = recipient.call{gas: 100000, value: 0}("");
return ok;
}
// IMPORTANT: call forwards all gas, so a malicious recipient
// can re-enter your contract. Always use a reentrancy guard.
}Verificação de Saldo
address.balance retorna o saldo em wei de qualquer endereço (incluindo address(this) para o próprio contrato). É view, gratuito de chamar off-chain. AVISO: o saldo pode ser inflado por qualquer um via selfdestruct (Ether forçado), então nunca confie em igualdade exata de saldo para lógica — use >= ou mantenha suas próprias variáveis de contabilidade. Sempre confira se a soma dos depósitos é igual ao saldo do contrato, como invariante.
contract BalanceCheck {
mapping(address => uint256) public deposits;
function deposit() public payable {
deposits[msg.sender] += msg.value;
}
function contractBalance() public view returns (uint256) {
// Balance of THIS contract
return address(this).balance;
}
function userBalance(address user) public view returns (uint256) {
// Balance of any address (in wei)
return user.balance;
}
function myBalance() public view returns (uint256) {
return msg.sender.balance;
}
// Verify accounting invariant
function verify() public view returns (bool) {
// Sum of deposits should equal contract balance
// (in a real contract, this would be expensive to compute)
return address(this).balance >= deposits[msg.sender];
}
// CAUTION: address.balance can be manipulated by an attacker
// who forces Ether via selfdestruct. Never use balance == X
// as a strict equality check for logic — use >= or tracking vars.
function dangerous() public view returns (bool) {
// BAD: an attacker can selfdestruct-ETH into the contract
// and break this exact check
return address(this).balance == 1 ether;
}
}Otimização de Gas
Storage vs Memory
Leituras de storage (SLOAD) custam ~2100 gas frias / 100 quentes por acesso. Leituras de memory (MLOAD) custam só 3 gas. Quando uma função lê uma variável de estado várias vezes (especialmente num loop), cacheie-a numa variável de memória primeiro. O primeiro SLOAD é caro; leituras de memória subsequentes são quase gratuitas. Esta é uma das otimizações mais fáceis e impactantes.
contract StorageVsMemory {
uint256 public stateVar; // storage slot 0
function expensive(uint256 x) public view returns (uint256) {
// Each access to stateVar = SLOAD (~2100 gas cold, 100 warm)
uint256 sum = 0;
for (uint256 i = 0; i < x; i++) {
sum += stateVar; // SLOAD every iteration
}
return sum;
}
function cheap(uint256 x) public view returns (uint256) {
// Cache to memory once: MLOAD costs 3 gas
uint256 cached = stateVar; // 1 SLOAD
uint256 sum = 0;
for (uint256 i = 0; i < x; i++) {
sum += cached; // MLOAD (cheap)
}
return sum;
}
// Rules of thumb:
// - storage: persistent, ~2100 gas per cold SLOAD, ~5000-20000 per SSTORE
// - memory: temporary, ~3 gas per access, free to create
// - calldata: read-only, free (passed in)
// Always cache state variables used multiple times in a function.
}Empacotamento de Variáveis
Solidity empacota variáveis de estado consecutivas em slots de storage de 32 bytes. Para economizar gas, agrupe tipos pequenos (uint8, uint64, address) juntos para compartilharem um slot. Reordene os campos de structs para que os pequenos empilhem apertados. Cada slot economizado = ~20k gas no primeiro acesso. Nota: entradas de mapping e array dinâmico sempre começam um slot novo e não podem ser empacotadas.
contract Packing {
// BAD: each takes a full 32-byte slot
// 3 slots = 60k gas for cold SLOADs
struct Bad {
uint64 time;
address from; // 20 bytes
uint64 amount;
}
// GOOD: pack small types together into 32 bytes
// 1 slot = 20k gas (one SLOAD)
struct Good {
uint64 time;
uint64 amount;
address from; // 20 bytes => total 8+8+20 = 36... still 2 slots
}
// Pack carefully: declare small types together
struct Packed {
uint32 a; // 4
uint32 b; // 4
uint32 c; // 4
uint32 d; // 4 => 16 bytes => can fit address (20)? No, 16+20=36 > 32
address e; // => 2 slots
}
struct Tight {
uint128 a; // 16
uint128 b; // 16 => 1 slot (32 bytes)
}
// Order matters: variables are packed in declaration order.
// A variable that doesn't fit starts a new slot.
// Mapping/dynamic-array always start a new slot.Blocos Unchecked
unchecked { ... } desativa checagens de overflow/underflow dentro do bloco, economizando gas (~50-80 por operação). Seguro quando você já validou os limites (ex.: depois de require(a >= b), a - b não pode dar underflow). O caso de uso seguro clássico é contadores de loop (i++ num for nunca vai transbordar 2^256). Não use unchecked às cegas — overflow silencioso é um risco de segurança.
contract UncheckedBlock {
function loopWith(uint256 n) public pure returns (uint256 sum) {
// 0.8+ checks overflow on every operation (extra gas)
for (uint256 i = 0; i < n; i++) {
sum += i;
}
}
function loopUnchecked(uint256 n) public pure returns (uint256 sum) {
unchecked {
for (uint256 i = 0; i < n; i++) {
sum += i; // skips overflow check (cheaper)
}
}
}
// Safe to use when overflow is impossible:
// - Loop counters that won't reach 2^256
// - Differences of values you've already bounds-checked
function safeSub(uint256 a, uint256 b) public pure returns (uint256) {
require(a >= b, "underflow"); // checked here
unchecked { return a - b; } // safe: can't underflow now
}
// NEVER use unchecked when overflow/underflow is possible
// unless you intentionally want wraparound (rare).
}Erros Personalizados vs Require
Erros personalizados (0.8.4+) são mais baratos que require(_, "msg") porque a string de mensagem é guardada no bytecode (custando gas por byte) e re-codificada a cada revert. Um erro personalizado é só um seletor de 4 bytes mais argumentos codificados em ABI. Para mensagens de erro não triviais, erros personalizados economizam milhares de gas por chamada E reduzem o tamanho do bytecode de implantação. Sempre prefira erros personalizados em código novo.
contract Errors {
// BAD: string messages bloat bytecode + cost gas per call
function oldStyle(uint256 x) public pure {
require(x > 0, "value must be greater than zero");
require(x < 100, "value must be less than one hundred");
}
// GOOD: custom errors are cheap and structured
error InvalidValue(uint256 given, uint256 min, uint256 max);
function newStyle(uint256 x) public pure {
if (x == 0 || x >= 100) {
revert InvalidValue(x, 1, 99);
}
}
// Gas comparison (approximate):
// require(_, "msg") ~ 400 + 50 per byte of message
// revert CustomError() ~ 400 + small selector cost
//
// For long messages, custom errors save thousands of gas
// and reduce deployed bytecode size.
// Define errors at file level to reuse across contracts
error Unauthorized(address caller);
function guarded() public {
if (msg.sender != address(0)) revert Unauthorized(msg.sender);
}
}Cache de Variáveis de Estado em Loops
Cacheie o comprimento do array numa variável local antes do loop (economiza um SLOAD por iteração). Se o array é pequeno, copie-o para memória uma vez (um SLOAD por elemento, depois MLOADs baratos no loop). Acumuladores devem ser sempre variáveis locais (memória). Para campos de structs de storage, cacheie o struct inteiro em memória se usado várias vezes.
contract Cache {
uint256[] public data;
mapping(address => uint256) public balances;
address[] public users;
// BAD: reads mapping in every iteration (SLOAD each time)
function sumBad() public view returns (uint256) {
uint256 total = 0;
for (uint256 i = 0; i < users.length; i++) {
total += balances[users[i]]; // SLOAD each iteration
}
return total;
}
// GOOD: cache length, use local var for accumulator
function sumBetter() public view returns (uint256) {
uint256 total = 0;
uint256 len = users.length; // cache length
for (uint256 i = 0; i < len; i++) {
address u = users[i]; // SLOAD once
total += balances[u]; // still SLOAD, but unavoidable
}
return total;
}
// BEST: cache array to memory (if small enough)
function sumMemory() public view returns (uint256) {
address[] memory memUsers = users; // copy to memory once
uint256 total = 0;
uint256 len = memUsers.length;
for (uint256 i = 0; i < len; i++) {
total += balances[memUsers[i]]; // MLOAD each iteration
}
return total;
}
}Curto-circuito e Otimização de Loops
Avaliação de curto-circuito: ponha checagens baratas primeiro em && e ||. Use ++i (prefixo) em vez de i++ (um pouco mais barato — sem temporário). Envolva contadores de loop em unchecked (i não transborda 2^256 de forma realista). Saia cedo dos loops quando achar o que precisa. Evite operações caras (chamadas externas, escritas de storage) dentro de loops — faça-as em lote fora.
contract ShortCircuit {
// && and || short-circuit: right side only evaluated if needed
function cheap(address a, address b) public view returns (bool) {
// Put the cheap check first
return (a == b || expensiveCheck(a));
}
function expensiveCheck(address) internal view returns (bool) {
// imagine a heavy computation
return true;
}
// Loop optimization: prefer prefix increment
function good() public pure returns (uint256) {
uint256 sum = 0;
for (uint256 i = 0; i < 10; ++i) { // ++i slightly cheaper than i++
sum += i;
}
return sum;
}
// Use unchecked for loop counters (always safe)
function best() public pure returns (uint256) {
uint256 sum = 0;
uint256 i = 0;
unchecked {
while (i < 10) {
sum += i;
++i;
}
}
return sum;
}
// Avoid unnecessary work: precompute, batch, early-exit
function find(uint256[] memory arr, uint256 target)
public pure returns (int256)
{
for (uint256 i = 0; i < arr.length; ++i) {
if (arr[i] == target) return int256(i); // early exit
}
return -1;
}
}Unidades de Tempo e Propriedades de Bloco
block.timestamp
block.timestamp (apelido 'now' pré-0.7.0) é o timestamp Unix do bloco atual, em segundos. É definido pelo minerador/validador e pode ser manipulado em ~15 segundos — NUNCA use para aleatoriedade ou precisão de tempo. Serve para durações grosseiras (>=1 minuto) e ordenação. Usos comuns: time-locks, cronogramas de vesting, prazos. Use block.number para garantias mais estritas.
contract Time {
uint256 public startTime;
uint256 public constant DURATION = 1 days;
constructor() {
startTime = block.timestamp; // uint256 in 0.8+
}
function isExpired() public view returns (bool) {
return block.timestamp >= startTime + DURATION;
}
function elapsed() public view returns (uint256) {
return block.timestamp - startTime;
}
// WARNING: block.timestamp is set by the miner/validator.
// They can manipulate it by ~15 seconds. NEVER use it for:
// - Randomness (keccak256(block.timestamp) is exploitable)
// - Precise timing (use block.number as a fallback)
// It's fine for:
// - Coarse durations (>= 1 minute)
// - Deadlines that tolerate 15s drift
// - Order of events (timestamp comparison)
// Time locks: require(block.timestamp > unlockTime)
function lock() public payable returns (uint256) {
return block.timestamp + 1 weeks;
}
}block.number e blockhash
block.number é a altura do bloco atual. blockhash(n) retorna o hash do bloco n, mas SÓ dos últimos 256 blocos (mais antigos retornam 0) e não do bloco atual (retorna 0). Tanto block.number quanto blockhash podem ser influenciados por mineradores, então não os use para aleatoriedade de alto risco. Para aleatoriedade real, use Chainlink VRF ou um esquema commit-reveal com entropia fornecida pelo usuário.
contract BlockInfo {
function currentBlock() public view returns (uint256) {
return block.number;
}
function prevHash(uint256 n) public view returns (bytes32) {
// Only the last 256 blocks' hashes are available
require(n > 0 && n <= 256, "out of range");
return blockhash(block.number - n);
}
// blockhash returns 0 for current block, future blocks, or >256 old
function currentHash() public view returns (bytes32) {
return blockhash(block.number); // returns 0!
}
// Use case: weak randomness (still exploitable by miners)
function pseudoRandom() public view returns (uint256) {
// A miner CAN see this and choose to withhold blocks
// to manipulate the result. Don't use for high value.
return uint256(keccak256(abi.encodePacked(
blockhash(block.number - 1),
block.timestamp,
msg.sender
)));
}
// For real randomness, use Chainlink VRF or a commit-reveal scheme.
}Unidades de Tempo (seconds/minutes/hours/days/weeks)
Sufixos de unidade de tempo (seconds, minutes, hours, days, weeks) convertem para segundos como uint256. 'years' foi removida na 0.5.0 pela ambiguidade de anos bissextos. Unidades de Ether (wei, gwei, ether) são separadas: 1 ether = 10^18 wei, 1 gwei = 10^9 wei. Sempre guarde quantias em wei e use os sufixos por legibilidade nos cálculos.
contract TimeUnits {
// Suffixes convert to seconds (uint256):
uint256 public oneSecond = 1 seconds; // 1
uint256 public oneMinute = 1 minutes; // 60
uint256 public oneHour = 1 hours; // 3600
uint256 public oneDay = 1 days; // 86400
uint256 public oneWeek = 1 weeks; // 604800
// 'years' was removed in 0.5.0 (leap years made it ambiguous)
function deadline() public view returns (uint256) {
return block.timestamp + 7 days;
}
function hourly() public pure returns (uint256) {
return 24 hours; // 86400
}
// Ether units (different from time units!):
uint256 public oneWei = 1 wei; // 1
uint256 public oneGwei = 1 gwei; // 10^9
uint256 public oneEther = 1 ether; // 10^18
function fromEther(uint256 e) public pure returns (uint256) {
return e * 1 ether; // convert to wei
}
function toEther(uint256 weiAmount) public pure returns (uint256) {
return weiAmount / 1 ether;
}
}Gas e gasleft()
gasleft() retorna o gas restante no ponto da chamada (substitui o msg.gas obsoleto). É útil para medir quanto gas um trecho de código consome. A regra 63/64: chamadas externas encaminham 63/64 do gas restante, mantendo 1/64 reservado para que o chamador trate o retorno. Não confie em valores exatos de gas entre hard forks — os custos dos opcodes mudam.
contract GasTrack {
function checkGas() public returns (uint256, uint256) {
uint256 start = gasleft(); // gas remaining at this point
// ...do some work...
uint256 sum = 0;
for (uint256 i = 0; i < 100; i++) {
sum += i;
}
uint256 end = gasleft();
return (start, start - end); // (initial, used)
}
// 63/64th rule: when an external call is made, only 63/64 of
// remaining gas is forwarded; 1/64 is reserved so the caller
// can finish processing (e.g., revert handling).
function forwardGas(address target) public returns (bool, uint256) {
uint256 before = gasleft();
(bool ok, ) = target.call{gas: 100000}("");
uint256 after = gasleft();
return (ok, before - after);
}
// gasleft() replaces the deprecated msg.gas.
// It's a view, so it can be used in modifiers to enforce budgets.
modifier usesLessThan(uint256 maxGas) {
uint256 start = gasleft();
_;
require(start - gasleft() <= maxGas, "too much gas");
}
}Chain ID e Detecção de Rede
block.chainid retorna o ID da chain atual. É essencial para proteção contra replay (EIP-155) e assinaturas de dados tipados EIP-712 (o separador de domínio inclui chainId). Cacheie chainId como immutable no construtor, por eficiência de gas, mas para EIP-712 você pode precisar recomputar se o contrato for forkado para uma nova chain. Sempre inclua chainId em qualquer hash que assine autorização.
contract Chain {
function getChainId() public view returns (uint256) {
return block.chainid; // current chain ID
}
// Common chain IDs:
// 1 = Ethereum mainnet
// 5 = Goerli testnet (deprecated)
// 11155111 = Sepolia testnet
// 137 = Polygon
// 42161 = Arbitrum One
// 10 = Optimism
// 56 = BNB Smart Chain
modifier onlyMainnet() {
require(block.chainid == 1, "only mainnet");
_;
}
// Prevent cross-chain replay attacks by including chainId in hashes
function domainSeparator() public view returns (bytes32) {
return keccak256(abi.encode(
keccak256("EIP712Domain(...)"),
block.chainid,
address(this)
));
}
// For multi-chain deployments, store chainId at construction
uint256 public immutable chainId;
constructor() {
chainId = block.chainid;
}
// NOTE: chainId can change during a fork (rare). For EIP-712
// signatures, cache it but allow re-initialization on mismatch.
}Modificadores de Visibilidade
Public
Funções public podem ser chamadas de qualquer lugar: externamente (por usuários ou outros contratos), internamente (de dentro do contrato) e de contratos derivados. Variáveis de estado públicas ganham automaticamente uma função getter. Public é a mais permissiva, mas adiciona bytecode (a função precisa suportar convenções de chamada internas e externas). Quando uma função public é chamada internamente via 'this.f()', vira uma chamada externa cara.
contract Public {
uint256 public counter; // public state var => auto getter
// public function: callable from anywhere
// - externally (via transaction or call)
// - internally (from this contract)
// - from derived contracts
function increment() public {
counter += 1;
}
function caller() public {
increment(); // internal call (cheap)
this.increment(); // external call (expensive, creates a msg)
}
// Public is the most permissive. Auto-getters for state vars
// are 'external' view functions generated by the compiler.
//
// Cost: public functions are part of the ABI and add bytecode.
// Internal calls to public functions skip the external wrapper.
}External
Funções external SÓ podem ser chamadas de fora do contrato — não internamente. São levemente mais baratas que public, porque leem direto do calldata (sem cópia para memória). Use external para funções que devem ser apenas pontos de entrada. Se precisar chamar uma função interna e externamente, faça-a public OU divida em um wrapper external + implementação internal.
contract External {
// external: ONLY callable from outside the contract
// CANNOT be called internally (this.f() works but is expensive)
function doWork(uint256 x) external pure returns (uint256) {
return x * 2;
}
function caller() public pure returns (uint256) {
// doWork(5); // COMPILER ERROR: external not callable internally
return this.doWork(5); // works but creates an external call (expensive)
}
// external with calldata params is cheapest for inputs
function process(string calldata input)
external
pure
returns (bytes32)
{
return keccak256(bytes(input));
}
// Use external when:
// - The function is only meant to be called by users/other contracts
// - You want to read calldata directly (cheaper than memory)
//
// State variables CANNOT be external.
}Internal
Funções internal podem ser chamadas de dentro do contrato e de qualquer contrato derivado (subclasses). É o padrão para variáveis de estado. internal é mais barata que public porque não precisa do wrapper de chamada externa. Use internal para funções auxiliares e lógica central que subclasses devem poder chamar ou sobrescrever. A convenção é prefixar funções internas com underscore (_helper).
contract Internal {
uint256 internal secret; // internal state var (default)
// internal: callable from this contract AND derived contracts
function _helper(uint256 x) internal pure returns (uint256) {
return x + 1;
}
function caller() public pure returns (uint256) {
return _helper(5); // internal call works
}
// Cannot be called externally:
// contract Other { function f() public { Internal._helper(5); } } // ERROR
}
contract Child is Internal {
function useParent() public pure returns (uint256) {
return _helper(10); // OK: child can call internal
}
function readSecret() public view returns (uint256) {
return secret; // OK: child can read internal
}
}
// internal is the DEFAULT for state variables.
// Use internal when:
// - You want subclasses to use/override it
// - You don't need external access
// It's cheaper than public (no external wrapper).Private
Funções e variáveis de estado private são acessíveis só dentro do contrato que as define — nem subclasses. É a visibilidade mais restritiva. CRÍTICO: 'private' NÃO significa secreto — qualquer dado da blockchain é publicamente legível via eth_getStorageAt e análise de bytecode. Use private só para impedir que outros contratos chamem/herdem; use criptografia/hashing para confidencialidade real.
contract Private {
uint256 private counter; // private state var
// private: ONLY callable from THIS contract (not even subclasses)
function _secret(uint256 x) private pure returns (uint256) {
return x * 42;
}
function caller() public pure returns (uint256) {
return _secret(5); // OK: same contract
}
}
contract Sub is Private {
// function useIt() public pure returns (uint256) {
// return _secret(5); // COMPILER ERROR: not accessible
// }
// function readCounter() public view returns (uint256) {
// return counter; // COMPILER ERROR: not accessible
// }
}
// IMPORTANT: 'private' does NOT mean hidden on-chain.
// All storage and bytecode are publicly readable via RPC.
// 'private' only means 'not part of the contract's ABI'
// and 'not callable/inheritable by other contracts'.
// For real confidentiality, use encryption or zero-knowledge proofs.Boas Práticas de Visibilidade
Boas práticas: use a visibilidade mais restritiva que funciona (private > internal > external > public). Evite variáveis de estado públicas, a menos que queira o getter automático — getters explícitos permitem adicionar validação depois. Use external+calldata para pontos de entrada. Prefixe helpers internos/privados com underscore. Cada função public/external adiciona bytecode; minimizar a ABI reduz gas de implantação e chamada.
contract Best {
// 1. Default to the MOST restrictive visibility that works.
// Order: private < internal < external < public
// 2. State variables: NEVER public unless you want a free getter.
// Prefer private/internal + explicit getter functions,
// so you can add validation/logic later.
uint256 private _balance;
function balance() public view returns (uint256) {
return _balance;
}
// 3. External functions: use 'external' + 'calldata' for entry points
function buy(uint256[] calldata ids) external payable {
for (uint256 i = 0; i < ids.length; i++) {
_buyOne(ids[i]);
}
}
// 4. Internal helper: prefix with underscore convention
function _buyOne(uint256 id) internal {
// ...
}
// 5. Private for truly internal-only logic
function _computeFee(uint256 amount) private pure returns (uint256) {
return amount / 100;
}
// 6. Avoid public functions that are never called externally
// (wastes bytecode). Make them internal.
}
// Summary: visibility is part of the contract's API design.
// Smaller ABI = less bytecode = lower deployment + call gas.Interação entre Contratos
Chamando Outros Contratos
Para chamar outro contrato, faça cast do endereço para um tipo de interface: IToken(addr).method(). Chamadas view são gratuitas off-chain, mas custam gas quando chamadas de uma transação. Sempre verifique os valores de retorno de chamadas que mudam estado (token.transfer retorna bool). Cast de endereço para interface NÃO verifica que o contrato realmente a implementa — se a função não existir, a chamada reverte.
interface IToken {
function balanceOf(address) external view returns (uint256);
function transfer(address, uint256) external returns (bool);
}
contract Caller {
IToken public token;
address public owner;
constructor(address _token) {
token = IToken(_token);
owner = msg.sender;
}
// Call a view function on another contract
function getBalance(address who) public view returns (uint256) {
return token.balanceOf(who); // external call
}
// Call a state-changing function
function sendTokens(address to, uint256 amount)
public returns (bool)
{
require(msg.sender == owner, "not owner");
bool ok = token.transfer(to, amount);
require(ok, "transfer failed");
return true;
}
// Cast any address to an interface (no validation!)
function checkAny(address maybeToken)
public view returns (uint256)
{
return IToken(maybeToken).balanceOf(address(this));
}
}Chamadas Baseadas em Interface
Use interfaces para interagir com qualquer contrato cuja ABI você conheça, sem precisar do fonte. Isso desacopla chamadores de implementações e funciona com qualquer token/protocolo que siga um padrão (ERC20, ERC721, feeds Chainlink). Interfaces mantêm seu bytecode pequeno (sem lógica herdada) e permitem escrever código genérico (uma carteira que funciona com qualquer ERC20). Sempre prefira interfaces a contratos concretos para chamadas externas.
interface IERC20 {
function name() external view returns (string memory);
function balanceOf(address) external view returns (uint256);
function transfer(address, uint256) external returns (bool);
}
contract Wallet {
IERC20 public immutable token;
address public owner;
constructor(address _token) {
token = IERC20(_token);
owner = msg.sender;
}
function tokenBalance() public view returns (uint256) {
return token.balanceOf(address(this));
}
function withdraw(uint256 amount) public {
require(msg.sender == owner, "not owner");
token.transfer(owner, amount);
}
function tokenName() public view returns (string memory) {
return token.name();
}
}
// Why use interfaces?
// - Decouple: Wallet doesn't need to know token implementation
// - Reusability: works with ANY ERC20 (USDC, DAI, WETH, ...)
// - Smaller bytecode: don't inherit the token's code
// - Standardization: IERC20 is a documented ABIChamada de Baixo Nível (call)
address.call(payload) é a chamada de mais baixo nível, retornando (bool, bytes). Use quando não tem uma interface, quer encaminhar calldata arbitrário ou precisa de controle fino (gas, valor). Construa calldata com abi.encodeWithSignature/Selector/Call. CRÍTICO: 'ok' é false só em falhas da EVM (revert, falta de gas), não em falhas lógicas — decodifique 'data' para inspecionar motivos de revert ou erros personalizados.
contract LowLevel {
// call: lowest-level call, returns (bool, bytes)
function callFn(address target, bytes memory payload)
public returns (bool, bytes memory)
{
(bool ok, bytes memory data) = target.call(payload);
require(ok, "call failed");
return (ok, data);
}
// With Ether
function callWithEth(address target, bytes memory payload)
public payable returns (bool, bytes memory)
{
(bool ok, bytes memory data) = target.call{value: msg.value}(payload);
return (ok, data);
}
// With gas limit
function callWithGas(address target, bytes memory payload, uint256 gas)
public returns (bool, bytes memory)
{
return target.call{gas: gas}(payload);
}
// Helpers to build calldata:
// abi.encodeWithSignature("transfer(address,uint256)", to, amount)
// abi.encodeWithSelector(bytes4(selector), to, amount)
// abi.encodeWithCall(IERC20.transfer.selector, to, amount)
// WARNING: low-level call returns true even if the called function
// reverts internally — you only get false on EVM-level failure.
// Decode 'data' to inspect custom errors or return values.
function safeCall(address target) public returns (uint256) {
(bool ok, bytes memory data) = target.call(
abi.encodeWithSignature("getValue()")
);
require(ok, "call reverted");
return abi.decode(data, (uint256));
}
}Delegatecall
delegatecall roda o código do alvo no contexto de storage do CHAMADOR — mudanças de estado afetam o chamador, não o alvo. msg.sender e msg.value são preservados. É a fundação de proxies atualizáveis (EIP-1967, UUPS) e do padrão Diamond (EIP-2535). CRÍTICO: o layout de storage precisa corresponder entre chamador e alvo, ou o estado corrompe. Sempre use um layout de storage compartilhado ou o padrão AppStorage.
contract Delegate {
// delegatecall: executes target's code in CALLER's context
// - msg.sender is the ORIGINAL caller (preserved)
// - msg.value is preserved
// - Storage reads/writes affect the CALLER, not the target
// - address(this) is the CALLER
uint256 public num;
address public sender;
function delegateSet(address target, uint256 value) public {
// target's setNum() runs in THIS contract's storage
(bool ok, ) = target.delegatecall(
abi.encodeWithSignature("setNum(uint256)", value)
);
require(ok, "delegatecall failed");
}
}
contract Target {
// MUST have the same storage layout as Delegate for sane behavior!
uint256 public num;
address public sender;
function setNum(uint256 value) public {
num = value;
sender = msg.sender; // this is the ORIGINAL caller, not Delegate
}
}
// Use cases:
// - Proxy patterns (EIP-1967, UUPS, Transparent): upgradeable logic
// - Diamond pattern (EIP-2535): modular facets
//
// DANGER: storage layout mismatch => corrupted state.
// Both contracts MUST declare variables in the same order/types.
// Use a shared storage contract or app storage pattern.Staticcall
staticcall executa o código do alvo, mas reverte se ocorrer qualquer modificação de estado — é a forma segura de ler de contratos não confiáveis. O compilador usa staticcall automaticamente quando você chama uma função view/pure via interface. Use staticcall diretamente quando quiser garantir uma chamada somente leitura a um contrato que pode mentir sobre ser view. Retorna (bool, bytes) como call.
contract Static {
// staticcall: like call, but REVERTS if the target modifies state.
// Used to safely READ from untrusted contracts.
function safeRead(address target, bytes memory payload)
public view returns (bytes memory)
{
(bool ok, bytes memory data) = target.staticcall(payload);
require(ok, "staticcall reverted");
return data;
}
function getBalance(address token, address who)
public view returns (uint256)
{
(bool ok, bytes memory data) = token.staticcall(
abi.encodeWithSignature("balanceOf(address)", who)
);
require(ok, "balanceOf failed");
return abi.decode(data, (uint256));
}
// Use cases:
// - Read from untrusted contracts without risk of state changes
// - Verify a contract behaves as a view function
// - Compose view-only queries across multiple contracts
// Distinguish from call():
// - call: allows state changes (target can write)
// - staticcall: forbids state changes (reverts if target writes)
// view/pure functions are called via staticcall automatically
// by the compiler when you call them normally.
function normalCall(IToken t, address who) public view returns (uint256) {
return t.balanceOf(who); // compiler emits staticcall
}
}
interface IToken { function balanceOf(address) external view returns (uint256); }Padrões de Segurança
Proteção contra Reentrância
A proteção contra reentrância é um mutex que impede uma função de ser reentrante enquanto ainda executa. Defina uma flag antes do corpo, libere depois. Isso previne o ataque clássico em que o receive/fallback de um contrato malicioso rechama withdraw() antes do saldo ser zerado (o padrão do hack do DAO). Aplique nonReentrant a qualquer função que faça chamada externa após mudança de estado — mesmo que também siga checks-effects-interactions (defesa em profundidade).
contract ReentrancyGuard {
// Classic mutex pattern using a storage flag
uint256 private _status = 1; // 1 = NOT_ENTERED, 2 = ENTERED
modifier nonReentrant() {
require(_status == 1, "REENTRANT");
_status = 2;
_;
_status = 1;
}
mapping(address => uint256) public balances;
function withdraw() public nonReentrant {
uint256 amount = balances[msg.sender];
require(amount > 0, "no balance");
// CRITICAL: update state BEFORE the external call
balances[msg.sender] = 0;
(bool ok, ) = msg.sender.call{value: amount}("");
require(ok, "send failed");
}
// Why needed: if we sent Ether FIRST, the attacker's receive()
// could call withdraw() again before balances was zeroed,
// draining the contract. This is the DAO hack pattern.
//
// Even with checks-effects-interactions, the guard is defense-in-depth.
// Apply nonReentrant to ANY function that:
// - Sends Ether to msg.sender
// - Calls an external contract
// - Then continues executing
}Checks-Effects-Interactions
Checks-Effects-Interactions (CEI) é o padrão de segurança mais importante: (1) rode todas as checagens require/validar, (2) atualize todas as variáveis de estado, (3) ENTÃO faça chamadas externas. Se uma chamada externa reentrar seu contrato, o estado já foi atualizado, então o atacante não pode gastar em dobro. CEI sozinho previne a maioria dos bugs de reentrância; pareie com um modificador nonReentrant por defesa em profundidade nas funções críticas.
contract CEI {
mapping(address => uint256) public balances;
// BAD: interaction BEFORE effect => reentrancy vulnerability
function vulnerable() public {
uint256 amount = balances[msg.sender];
(bool ok, ) = msg.sender.call{value: amount}(""); // INTERACTION
require(ok);
balances[msg.sender] = 0; // EFFECT (too late!)
// Attacker's receive() re-called this; balances still has funds.
}
// GOOD: checks, then effects, then interactions
function safe() public {
// 1. CHECKS: validate conditions
uint256 amount = balances[msg.sender];
require(amount > 0, "no balance");
// 2. EFFECTS: update state BEFORE external calls
balances[msg.sender] = 0;
// 3. INTERACTIONS: external calls LAST
(bool ok, ) = msg.sender.call{value: amount}("");
require(ok, "send failed");
// If attacker re-enters, balances[msg.sender] is already 0.
}
// Pattern: order your code as
// require() checks first,
// state updates second,
// external calls last.
// This single rule prevents most reentrancy bugs.
// Pair with nonReentrant for defense-in-depth.
}Pull sobre Push
Pull sobre Push: em vez de empurrar Ether a muitos destinatários numa transação (em que um destinatário ruim bloqueia tudo), credite o saldo de cada usuário e deixe-os puxar seus fundos via withdraw(). Isso isola falhas (o receive/fallback ruim de um usuário não bloqueia os outros) e reduz o gas por transação. Use para airdrops, trocas, pagamentos de leilão, reembolsos. Combinado com nonReentrant em withdraw().
contract PullOverPush {
// BAD (push): send Ether to many recipients in one tx
// If any recipient reverts (or is a contract that blocks), the WHOLE tx fails.
mapping(address => uint256) public pendingWithdrawals;
function pushPay(address[] memory recipients) public payable {
uint256 share = msg.value / recipients.length;
for (uint256 i = 0; i < recipients.length; i++) {
// If recipients[i].call fails, the whole loop reverts.
(bool ok, ) = recipients[i].call{value: share}("");
require(ok, "push failed");
}
}
// GOOD (pull): credit each user, let them withdraw individually
function credit(address[] memory recipients) public payable {
uint256 share = msg.value / recipients.length;
for (uint256 i = 0; i < recipients.length; i++) {
pendingWithdrawals[recipients[i]] += share; // just update state
}
}
function withdraw() public {
uint256 amount = pendingWithdrawals[msg.sender];
require(amount > 0, "nothing to withdraw");
pendingWithdrawals[msg.sender] = 0; // effect
(bool ok, ) = msg.sender.call{value: amount}(""); // interaction
require(ok, "withdraw failed");
}
// Pull pattern isolates failures: one user's failed withdrawal
// doesn't block others. Common in: airdrops, exchanges, auctions.
}Padrão Pausable
O padrão Pausable adiciona uma parada de emergência: um booleano 'paused' que gateia funções críticas via o modificador whenNotPaused. O owner pode pausar/despausar. Use como disjuntor quando um bug ou ataque é detectado — pause para estancar o dano enquanto prepara uma correção. Frequentemente combinado com proxies atualizáveis (pausar, depois implantar lógica corrigida). A OpenZeppelin fornece um contrato Pausable testado em batalha — use-o em vez de fazer o seu.
contract Pausable {
bool public paused;
address public owner;
constructor() { owner = msg.sender; }
modifier whenNotPaused() {
require(!paused, "contract is paused");
_;
}
modifier whenPaused() {
require(paused, "contract is not paused");
_;
}
modifier onlyOwner() {
require(msg.sender == owner, "not owner");
_;
}
function pause() public onlyOwner whenNotPaused {
paused = true;
}
function unpause() public onlyOwner whenPaused {
paused = false;
}
// Critical functions check whenNotPaused
function deposit() public payable whenNotPaused {
// ...
}
function withdraw(uint256 amount) public whenNotPaused {
// ...
}
// Use case: emergency stop. If a bug is discovered, pause the
// contract to prevent further damage while a fix is prepared.
// Often combined with upgradeable proxies to deploy a patched version.
}
// OpenZeppelin provides Pausable as a reusable contract.Controle de Acesso
Padrões de controle de acesso: (1) Ownable — owner único com o modificador onlyOwner (simples, centralizado). (2) RBAC — baseado em papéis com papéis bytes32 e o modificador onlyRole (flexível, multi-admin). (3) Multi-sig ou Timelock — para contratos de alto valor, confie ao Gnosis Safe ou ao Timelock da OpenZeppelin. CRÍTICO: sempre use msg.sender para auth, NUNCA tx.origin (que pode ser falsificado por contratos intermediários maliciosos). A OpenZeppelin fornece Ownable e AccessControl.
contract AccessControl {
// 1. Simple owner (Ownable pattern)
address public owner;
constructor() { owner = msg.sender; }
modifier onlyOwner() {
require(msg.sender == owner, "not owner");
_;
}
function setOwner(address newOwner) public onlyOwner {
require(newOwner != address(0), "zero address");
owner = newOwner;
}
// 2. Role-based (RBAC)
mapping(bytes32 => mapping(address => bool)) public roles;
bytes32 public constant ADMIN = keccak256("ADMIN");
bytes32 public constant MINTER = keccak256("MINTER");
modifier onlyRole(bytes32 role) {
require(roles[role][msg.sender], "missing role");
_;
}
function grantRole(bytes32 role, address account)
public onlyRole(ADMIN)
{
roles[role][account] = true;
}
function revokeRole(bytes32 role, address account)
public onlyRole(ADMIN)
{
roles[role][account] = false;
}
function mint(address to, uint256 amount) public onlyRole(MINTER) {
// ...
}
// 3. Multi-sig / time-locked (defer to Gnosis Safe or OpenZeppelin Timelock)
// Always use msg.sender (NOT tx.origin) for authorization.
// tx.origin can be spoofed if a user interacts with a malicious
// intermediate contract.
}Padrão de Token ERC20
Interface ERC20
ERC-20 é o padrão para tokens fungíveis (USDC, DAI, UNI). A interface define 6 funções obrigatórias (totalSupply, balanceOf, transfer, allowance, approve, transferFrom) e 2 eventos (Transfer, Approval). Metadados opcionais (name, symbol, decimals) são implementados universalmente. Sempre use o contrato base ERC20 da OpenZeppelin para tokens novos — é auditado, trata casos extremos e é reconhecido por carteiras/DEXs.
interface IERC20 {
// Events
event Transfer(address indexed from, address indexed to, uint256 value);
event Approval(address indexed owner, address indexed spender, uint256 value);
// Metadata (optional but standard)
function name() external view returns (string memory);
function symbol() external view returns (string memory);
function decimals() external view returns (uint8);
// Required functions
function totalSupply() external view returns (uint256);
function balanceOf(address account) external view returns (uint256);
function transfer(address to, uint256 amount) external returns (bool);
function allowance(address owner, address spender)
external view returns (uint256);
function approve(address spender, uint256 amount) external returns (bool);
function transferFrom(address from, address to, uint256 amount)
external returns (bool);
}
// ERC-20 is THE standard for fungible tokens (USDC, DAI, UNI, ...).
// Implemented by thousands of tokens; supported by every wallet/Dex.
// Implementing the interface correctly ensures interoperability.
// Use OpenZeppelin's ERC20 base contract — battle-tested and audited.Função Transfer
transfer(para, quantia) move tokens do chamador para 'para'. Checagens padrão: endereço de destinatário não nulo, saldo suficiente. Atualize os saldos ANTES de emitir o evento Transfer (padrão CEI). Mint é modelado como Transfer de address(0); burn é Transfer para address(0). O campo decimals (geralmente 18) significa que as quantias estão em unidades atômicas (equivalente a wei); UIs dividem por 10^decimals para exibir.
contract SimpleToken is IERC20 {
string public name = "Simple Token";
string public symbol = "SIM";
uint8 public constant decimals = 18;
uint256 public totalSupply;
mapping(address => uint256) public balanceOf;
mapping(address => mapping(address => uint256)) public allowance;
constructor(uint256 _initialSupply) {
totalSupply = _initialSupply;
balanceOf[msg.sender] = _initialSupply;
emit Transfer(address(0), msg.sender, _initialSupply);
}
function transfer(address to, uint256 amount) external returns (bool) {
require(to != address(0), "zero address");
require(balanceOf[msg.sender] >= amount, "insufficient");
balanceOf[msg.sender] -= amount;
balanceOf[to] += amount;
emit Transfer(msg.sender, to, amount);
return true;
}
// Note: 0.8+ auto-checks underflow, so we can simplify:
// balanceOf[msg.sender] -= amount;
// If insufficient, it reverts automatically.
// But explicit require gives clearer error messages.
}Approve e Allowance
approve(gastador, quantia) define quanto o 'gastador' pode transferir em seu nome (via transferFrom). Comum para DEXs e staking. AVISO: a condição de corrida do approve — mudar o allowance de A para B deixa um atacante gastar tanto A quanto B se ele adiantar a frente. Mitigue definindo 0 primeiro, depois o novo valor, OU use increaseAllowance/decreaseAllowance (OpenZeppelin). O evento Approval deve ser emitido a cada mudança.
contract ApprovalExample is IERC20 {
mapping(address => uint256) public balanceOf;
mapping(address => mapping(address => uint256)) public allowance;
// approve: allow 'spender' to spend up to 'amount' on your behalf
function approve(address spender, uint256 amount) external returns (bool) {
require(spender != address(0), "zero address");
allowance[msg.sender][spender] = amount;
emit Approval(msg.sender, spender, amount);
return true;
}
// Common use cases:
// - DEX trading: approve the DEX router to spend your tokens
// - Staking: approve the staking contract
// - Subscriptions: approve a recurring spender
// WARNING: the approve race condition.
// If you change allowance from 100 to 50, an attacker who saw 100
// could spend 100 BEFORE your tx, then spend 50 AFTER = 150 total.
// Mitigation (EIP-20): set to 0 first, then to new value.
// approve(spender, 0); approve(spender, 50);
// Or use increaseAllowance / decreaseAllowance (OpenZeppelin).
function increaseAllowance(address spender, uint256 added)
public returns (bool)
{
uint256 newAllowance = allowance[msg.sender][spender] + added;
allowance[msg.sender][spender] = newAllowance;
emit Approval(msg.sender, spender, newAllowance);
return true;
}
}TransferFrom
transferFrom(de, para, quantia) permite que um gastador aprovado mova tokens de 'de' para 'para'. O allowance do gastador deve ser >= quantia; decremente o allowance como parte do efeito (CEI). Usado por roteadores de DEX, contratos de staking e qualquer fluxo baseado em pull. Peculiaridades de tokens: USDT não decrementa o allowance; alguns tokens revertem em transferências para endereço zero. Sempre teste com o token específico antes de integrar.
contract TransferFromExample is IERC20 {
mapping(address => uint256) public balanceOf;
mapping(address => mapping(address => uint256)) public allowance;
// transferFrom: spender moves tokens from 'from' to 'to'
// Requires allowance[from][spender] >= amount
function transferFrom(address from, address to, uint256 amount)
external returns (bool)
{
require(to != address(0), "zero address");
require(balanceOf[from] >= amount, "insufficient balance");
require(allowance[from][msg.sender] >= amount, "insufficient allowance");
// Update allowance FIRST (CEI)
allowance[from][msg.sender] -= amount;
balanceOf[from] -= amount;
balanceOf[to] += amount;
emit Transfer(from, to, amount);
return true;
}
// Used by:
// - DEX routers (user approves router, router calls transferFrom)
// - Staking contracts
// - Any 'pull' workflow where a contract takes tokens from a user
// Note on infinite allowance:
// Some tokens (USDT) do NOT decrement allowance on transferFrom,
// and others set allowance to max uint256 by default. Read the
// specific token's docs before integrating.
}Eventos ERC20
ERC-20 define dois eventos: Transfer (emitido a cada movimento de token, incluindo mint de address(0) e burn para address(0)) e Approval (emitido a cada mudança de allowance). Esses eventos são como dApps e indexadores (The Graph, Dune, Etherscan) acompanham a atividade de tokens sem consultar o estado diretamente. Sempre os emita — omitir eventos quebra a interoperabilidade com carteiras e exchanges que dependem dos logs.
contract ERC20Events {
event Transfer(address indexed from, address indexed to, uint256 value);
event Approval(address indexed owner, address indexed spender, uint256 value);
mapping(address => uint256) public balanceOf;
mapping(address => mapping(address => uint256)) public allowance;
uint256 public totalSupply;
function _mint(address to, uint256 amount) internal {
require(to != address(0), "zero address");
totalSupply += amount;
balanceOf[to] += amount;
// Minting = transfer from address(0)
emit Transfer(address(0), to, amount);
}
function _burn(address from, uint256 amount) internal {
require(balanceOf[from] >= amount, "insufficient");
balanceOf[from] -= amount;
totalSupply -= amount;
// Burning = transfer to address(0)
emit Transfer(from, address(0), amount);
}
function _approve(address owner, address spender, uint256 amount) internal {
emit Approval(owner, spender, amount);
}
// Events let dApps and indexers (The Graph, Dune) track:
// - Every transfer (incl. mint/burn)
// - Every approval change
// - Token holdings over time
// Without events, integrating with wallets/DEXs is much harder.
}Implantação e Testes
Remix IDE
Remix é a forma mais fácil de começar com Solidity — uma IDE de navegador, sem instalação. Inclui um compilador, uma VM JavaScript para testes locais, implantação em testnets, um depurador de transações e análise estática. Ótimo para aprender e prototipar. Para produção, mude para Hardhat ou Foundry para scripting, testes automatizados e integração com CI/CD.
// Remix is a browser-based IDE for Solidity.
// URL: https://remix.ethereum.org
// Features:
// - File explorer, editor, compiler, deployer in one tab
// - Built-in Solidity compiler (no install needed)
// - Deploy to JavaScript VM, local node, or testnet
// - Interact with deployed contracts via GUI
// - Debug transactions step-by-step
// - Static analysis tools (Remix Analyzer)
// Workflow:
// 1. Create a .sol file in the File Explorer
// 2. Compile in the "Solidity Compiler" tab (pick version)
// 3. Deploy in the "Deploy & Run Transactions" tab
// 4. Interact via the deployed contract panel
// Good for: learning, prototyping, quick tests, debugging.
// Not ideal for: production workflows, automated testing, scripting.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
contract Hello {
string public msg = "Hello from Remix";
}Setup do Hardhat
Hardhat é um ambiente de desenvolvimento baseado em JavaScript/TypeScript. Instale via npm, configure redes e compilador no hardhat.config.ts. Fornece compilação, testes (Mocha/Chai), um nó local (hardhat node), scripts de implantação e console. O pacote de plugins Hardhat Toolbox inclui ethers.js, chai, typechain e mais. Use .env para segredos (chaves privadas, URLs de RPC).
// Hardhat: JavaScript/TypeScript development environment
// Install: npm install --save-dev hardhat
// Init: npx hardhat init
// hardhat.config.ts
import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";
const config: HardhatUserConfig = {
solidity: {
version: "0.8.19",
settings: { optimizer: { enabled: true, runs: 200 } },
},
networks: {
hardhat: {}, // built-in local network
sepolia: {
url: `${process.env.ALCHEMY_URL}`,
accounts: [process.env.PRIVATE_KEY ?? ""],
},
},
};
export default config;
// Project layout:
// contracts/ Solidity source files
// scripts/ deployment scripts (JS/TS)
// test/ test files (Chai/Mocha)
// ignition/ Hardhat Ignition modules (declarative deploy)
// Common commands:
// npx hardhat compile
// npx hardhat test
// npx hardhat run scripts/deploy.ts --network sepolia
// npx hardhat node // start local node
// npx hardhat console // interactive REPLTestes do Hardhat
Testes do Hardhat usam Mocha + Chai + ethers.js. getSigners() retorna contas de teste com ETH. connect(addr) envia uma tx de uma conta específica. Asserções: igualdade (equal), reverts (revertedWith), eventos (emit + withArgs). TypeChain gera automaticamente tipos TypeScript a partir das suas ABIs, dando autocomplete e checagens em tempo de compilação. Rode os testes com 'npx hardhat test'.
// test/Token.test.ts
import { expect } from "chai";
import { ethers } from "hardhat";
import { Token } from "../typechain-types";
describe("Token", () => {
let token: Token;
let owner: any, addr1: any;
beforeEach(async () => {
[owner, addr1] = await ethers.getSigners();
const Factory = await ethers.getContractFactory("Token");
token = await Factory.deploy(1000);
await token.waitForDeployment();
});
it("assigns initial supply to owner", async () => {
expect(await token.balanceOf(owner.address)).to.equal(1000);
});
it("transfers tokens between accounts", async () => {
await token.transfer(addr1.address, 100);
expect(await token.balanceOf(addr1.address)).to.equal(100);
});
it("reverts on insufficient balance", async () => {
await expect(
token.connect(addr1).transfer(owner.address, 1)
).to.be.revertedWith("insufficient");
});
it("emits Transfer event", async () => {
await expect(token.transfer(addr1.address, 100))
.to.emit(token, "Transfer")
.withArgs(owner.address, addr1.address, 100);
});
});
// Run: npx hardhat test
// TypeChain generates typed contract bindings in typechain-types/.Setup do Foundry
Foundry (forge) é um toolkit rápido baseado em Rust em que os testes são escritos no próprio Solidity — sem necessidade de JavaScript/TypeScript. Instale via foundryup. Ferramentas-chave: forge (build, teste, script), cast (CLI para chamadas RPC), anvil (nó local), chisel (REPL Solidity). É mais rápido que o Hardhat e inclui fuzz testing embutido. Dependências são submódulos git em lib/. A config vive no foundry.toml.
// Foundry: Rust-based, fast Solidity dev toolkit
// Install: curl -L https://foundry.paradigm.xyz | bash
// foundryup
// Init: forge init my-project
// Project layout:
// src/ Solidity sources (Default = src/Contract.sol)
// test/ Solidity tests (*.t.sol)
// script/ Deployment scripts (*.s.sol)
// lib/ Dependencies (git submodules, e.g. forge-std, openzeppelin)
// Commands:
// forge build // compile
// forge test // run tests
// forge test -vvv // verbose (shows console logs)
// forge coverage // code coverage
// forge script script/Deploy.s.sol --rpc-url $RPC --broadcast
// Foundry config (foundry.toml):
// [profile.default]
// src = "src"
// out = "out"
// libs = ["lib"]
// solc = "0.8.19"
// optimizer = true
// optimizer_runs = 200
// Why Foundry?
// - Tests are written IN Solidity (no JS/TS context switch)
// - Extremely fast (parallelized, cached)
// - Built-in fuzzing and invariant testing
// - Cast/anvil/chisel CLI tools includedTestes do Foundry (Solidity)
Testes do Foundry são contratos Solidity estendendo forge-std/Test. Use assertEq, assertTrue etc. para asserções. Cheatcodes (vm.*) manipulam a EVM: vm.prank para falsificar msg.sender, vm.warp para definir o tempo, vm.deal para cunhar ETH, vm.expectRevert para afirmar falhas. Testes de fuzz (testFuzz_*) geram automaticamente entradas aleatórias dentro de restrições (vm.assume). Testes de invariante (testInvariant_*) rodam sequências aleatórias para achar invariantes quebrados.
// test/Token.t.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;
import "forge-std/Test.sol";
import "../src/Token.sol";
contract TokenTest is Test {
Token public token;
address owner = address(this);
address user = address(0x1);
function setUp() public {
token = new Token(1000);
}
function testInitialSupply() public view {
assertEq(token.balanceOf(owner), 1000);
}
function testTransfer() public {
token.transfer(user, 100);
assertEq(token.balanceOf(user), 100);
}
function testRevertOnInsufficient() public {
vm.expectRevert("insufficient");
token.transfer(user, 99999);
}
// Fuzz test: 'x' is randomized by the framework
function testFuzzTransfer(uint256 x) public {
vm.assume(x <= 1000);
token.transfer(user, x);
assertEq(token.balanceOf(user), x);
}
// Cheatcodes (vm.*):
// vm.prank(addr) // next call from addr
// vm.startPrank(addr) // all subsequent calls from addr
// vm.warp(timestamp) // set block.timestamp
// vm.roll(blockNum) // set block.number
// vm.deal(addr, 1 ether) // give ETH to addr
// vm.expectRevert(...) // assert next call reverts
// vm.expectEmit(...) // assert next call emits event
}
// Run: forge test -vvvSnippets de Solidity relacionados
Copy-paste ready code for common tasks.
Básico de Contratos
Definir um smart contract básico com estado e funções.
Funções e Visibilidade
Visibilidade de função, payable e valores de retorno.
Modifiers e Controle de Acesso
Reutilizar lógica de validação com modifiers.
Events e Logs
Emitir events para listeners off-chain.
Mappings, Structs & Storage Aninhado
Agrupar dados relacionados com structs e consultá-los por chave com mappings.
Herança, Abstract & Interfaces
Reutilizar lógica via herança; definir contratos com abstract e interface.
Payable, receive & fallback (fluxos de ETH)
Receber ETH via funções payable e os hooks receive/fallback.
Reentrância & Checks-Effects-Interactions
Endurecer contratos contra o ataque de smart contract mais comum.
Was this helpful?