Mapping in Solidity: The Workhorse Key-Value Lookup

mapping(address => uint256) public balances;
mapping(address => bool)    public allowed;
mapping(uint256 => address) public ownerOf;            // ERC721 style

// Nested mapping — common for ERC20 allowance(owner, spender)
mapping(address => mapping(address => uint256)) public allowance;

Declaring a mapping public gives you a free getter named after the mapping. Calling balances(someAddress) from a wallet returns the stored value. Inside the contract you read it as balances[someAddress].

Imagine an unbounded sparse array indexed by every possible address. Most of the array is implicitly zero. Writing balances[alice] = 100 stores 100 at the address derived from keccak256(alice || slotOfBalances). Reading the same key reproduces the same hash and finds the same slot. There is never any list of who has been seen — the mapping has no notion of cardinality. To compute the actual value slot for a given mapping and key without writing a script, use the mapping calculator inside the Solidity Storage Layout Visualizer.

// 1. Per-user state
mapping(address => uint256) public balances;

balances[msg.sender] += msg.value;

// 2. Mapping to a struct (the workhorse)
struct Position {
    uint256 collateral;
    uint256 debt;
    uint64  openedAt;
}
mapping(address => Position) public positions;

positions[user].collateral += amount;

// 3. Nested mapping for two-key lookup
mapping(address => mapping(uint256 => bool)) public hasClaimed;

hasClaimed[msg.sender][campaignId] = true;

Pattern 2 is by far the most common. A mapping to a struct gives you a clean way to bundle several fields under one identifier. Token contracts, lending pools, vaults, and prediction markets all use it.

mapping(address => uint256) public balances;
address[] public users;                          // parallel index
mapping(address => bool) private isKnown;

function deposit() external payable {
    if (!isKnown[msg.sender]) {
        users.push(msg.sender);
        isKnown[msg.sender] = true;
    }
    balances[msg.sender] += msg.value;
}

function totalUsers() external view returns (uint256) {
    return users.length;
}

Notice the safety check — push to the array only the first time we see this address, otherwise the array would grow on every deposit. OpenZeppelin's EnumerableSet ships exactly this pattern in audited form.

Beware: iterating a large dynamic array on chain can hit the block gas limit and brick the function. If you expect tens of thousands of entries, do the iteration off chain by reading events instead.

The pillar guide is the Solidity smart contracts beginner guide. The most common value type stored inside a mapping is covered in uint and uint256 and the most common key type in the address type. To bundle multiple fields per key, see structs in Solidity. For ordered or enumerable lists, read arrays in Solidity.