Solidity Arrays with Loops: Smart Contract Examples

The pattern is everywhere: tallying votes across proposals, computing the total supply of a token across holders, finding the highest bidder in an auction, distributing a reward to a list of recipients. All of them are arrays plus loops.

uint256[] public scores;

function totalScore() external view returns (uint256 total) {
    uint256 len = scores.length;          // cache once
    for (uint256 i; i < len; ++i) {
        total += scores[i];
    }
}

That five line function shows the canonical shape: declare the array, cache its length, set up a counter, walk the indices, accumulate. Every other loop in this guide is a variation of this pattern with a different body.

For the standalone primitives, see arrays in Solidity and mapping in Solidity. This piece assumes you know how to declare an array and focuses on the iteration patterns you will actually write in production.

The for loop is the workhorse. You declare the counter, the stop condition, and the increment all in one line, and the body runs as long as the condition holds.

for (uint256 i; i < arr.length; ++i) {
    // body
}

The while loop is for cases where you do not know the iteration count up front. A delegation chain walk, a binary search, or a state driven retry loop are typical examples.

address current = msg.sender;
while (delegations[current] != address(0)) {
    current = delegations[current];
}
// current is now the head of the delegation chain

The do while loop runs the body once before checking the condition. It rarely appears in on chain code because most Solidity loops require the condition to hold from the start. You may see it in retry helpers and verification routines that must execute one iteration unconditionally.

You already have the mapping with struct setup from the companion piece on mapping with struct. Two structs, two mappings, and a parallel proposals array. The contract now needs a function that returns which proposal won. That is a for loop with a running max:

struct Proposal {
    bytes32  name;
    uint128  voteCount;
    uint64   endsAt;
}

Proposal[] public proposals;

function winningProposal()
    public
    view
    returns (uint256 winnerIndex)
{
    uint256 winningCount;
    uint256 len = proposals.length;
    for (uint256 i; i < len; ++i) {
        if (proposals[i].voteCount > winningCount) {
            winningCount = proposals[i].voteCount;
            winnerIndex = i;
        }
    }
}

function winnerName() external view returns (bytes32) {
    return proposals[winningProposal()].name;
}

A few details earn their keep. The function is view, so calling it through eth_call costs the user no real gas. The loop reads each proposal once. If two proposals tie, the first one found wins because the comparison is strict greater than. This matches the behaviour of the canonical OpenZeppelin governor contract, where ties are resolved by declaration order.

What if you also want to know how many votes the winner received? Return both:

function winnerWithCount()
    external
    view
    returns (uint256 winnerIndex, uint256 winningCount)
{
    uint256 len = proposals.length;
    for (uint256 i; i < len; ++i) {
        if (proposals[i].voteCount > winningCount) {
            winningCount = proposals[i].voteCount;
            winnerIndex = i;
        }
    }
}

That is the same loop with two named return values. The compiler initialises both to zero, so the first iteration always sets them. The pattern generalises to any walk that returns running aggregates: total supply, average, count above a threshold, first matching index.

The pathology is always the same. A function loops over an array. The array grows over time as users register, claim, or stake. The gas cost grows linearly with the array length. At some point the cost exceeds the block gas limit (currently 30 million on Ethereum mainnet), and from that moment every transaction calling the function reverts before it can finish. There is no upgrade path that does not involve migrating state to a new contract.

// DO NOT WRITE THIS in production.
//
// distributeRewards loops over every holder. The contract works fine
// at 100 holders. At 100 000 holders the function becomes uncallable
// forever and the rewards locked in the contract are stuck.
function distributeRewards() external {
    uint256 perUser = address(this).balance / holders.length;
    for (uint256 i; i < holders.length; ++i) {
        payable(holders[i]).transfer(perUser);
    }
}

The first fix is pagination. Instead of one function that walks the entire array, expose a function that walks a window. The caller passes the start index and the count, the function processes that slice, and a separate state variable tracks the next start. This works well for one time operations like distributing a fixed reward pool.

uint256 public nextRecipient;

function distributeBatch(uint256 batchSize) external {
    uint256 end = nextRecipient + batchSize;
    if (end > holders.length) end = holders.length;
    for (uint256 i = nextRecipient; i < end; ++i) {
        payable(holders[i]).transfer(rewardPerUser);
    }
    nextRecipient = end;
}

function distributionDone() external view returns (bool) {
    return nextRecipient == holders.length;
}

The second fix, almost always preferred, is pull over push. Track per user balances in a mapping and let each user pull their own share when they want it. This shifts the gas cost from the protocol to each user, eliminates the loop entirely, and removes the reentrancy surface created by external calls inside a batch.

mapping(address => uint256) public claimable;

function recordReward(address user, uint256 amount) external onlyAuthorized {
    claimable[user] += amount;
}

function claim() external {
    uint256 amount = claimable[msg.sender];
    require(amount > 0, "nothing to claim");
    claimable[msg.sender] = 0;        // effects before interactions
    payable(msg.sender).transfer(amount);
    emit Claimed(msg.sender, amount);
}

The pull pattern is exactly the mapping with struct shape from the companion piece. You replace one expensive batch loop with one O(1) write per user during accrual, and one O(1) withdraw per user during claim. The total work done across all users is the same. The difference is that no single transaction has to do all of it.

If your loop produces a single number — a Merkle root, a sum, an aggregate score — you can compute that number off chain and submit it on chain along with a proof. The contract verifies the proof in constant time and stores the result. This is how every serious airdrop is structured in 2026.

bytes32 public merkleRoot;

function setRoot(bytes32 newRoot) external onlyOwner {
    merkleRoot = newRoot;
}

function claim(uint256 amount, bytes32[] calldata proof) external {
    bytes32 leaf = keccak256(abi.encodePacked(msg.sender, amount));
    require(verify(proof, merkleRoot, leaf), "bad proof");
    require(!claimed[msg.sender], "already claimed");
    claimed[msg.sender] = true;
    token.transfer(msg.sender, amount);
}

Off chain you build the full holder list and compute the Merkle root. On chain you store one bytes32. Each user submits a proof of their entry, the contract verifies it in O(log n) hashes regardless of total participants, and the transfer happens. A holder list of one million users is no more expensive on chain than a list of one hundred.