Mapping vs Array for Dynamic Collection Storage

Answer to the Key Questions

1. Does the dual‑structure overhead outweigh iterating a large array?

In Solidity 0.8.x a single mapping insertion costs roughly 200 gas for the storage write, while pushing a key into a dynamic array costs another 200 gas (plus the cost of resizing the array if the capacity is exceeded). Thus a write that updates both structures is about 400 gas. In contrast, iterating over an array of N elements incurs ~200 gas per iteration (the exact cost depends on the loop body). For example, enumerating 5 000 entries consumes ~1 M gas, which is a significant fraction of a 30 M block limit.

Therefore, if you write often but read rarely, the 400 gas per write is acceptable. If you read often and the collection grows large, the cost of enumerating can quickly dominate, making the dual‑structure less attractive.

2. When does an array‑only approach become risky?

With a 30 M gas block limit, a single transaction that enumerates an array can safely handle up to roughly 30 000 000 / 200 ≈ 150 000 elements if the loop body is minimal. However, real contracts add extra gas for checks, event emissions, and state changes, so a safe upper bound is usually 10 000–20 000 items for enumeration‑heavy functions. Beyond that, a single transaction will hit the block gas limit, leading to DoS‑like failures.

Practical Decision Guide

1. Identify the dominant operation:
   • Key‑based lookup, insertion, or deletion → mapping.
   • Position‑based access or strict ordering → array.
2. Estimate write frequency vs read frequency.
   • High writes, low reads → mapping alone or mapping+array if enumeration is occasional.
   • High reads, especially enumeration → array‑only if size stays below ~10 k; otherwise use mapping+array and provide pagination.
3. Check gas budget:
   • For enumeration, calculate gasPerIteration * N and compare to the block gas limit minus overhead.
   • If the result exceeds the limit, design the function to return paginated slices or use an off‑chain index.
4. Verify with a small benchmark in Remix or Hardhat:
   • Deploy a contract that inserts 1 000 000 items into both structures.
   • Measure gas for a single write and for a loop that iterates over all items.
5. Consider storage cost:
   • Mappings store only the value at the hash slot; arrays store each element plus the length slot. For large collections, arrays can be cheaper in storage but more expensive in gas for writes.

Missing Diagnostic Detail

To refine the recommendation, please provide the current block gas limit (e.g., 30 M, 15 M) and the expected maximum number of active entries in your collection. These figures will allow a precise calculation of enumeration feasibility.