In my free time iwrite and raise my voice in toast.
Introduction
Every smart contract deployed on the Ethereum blockchain manipulates data — balances, ownership records, governance proposals, order books, and more. While simple values like a single integer or a boolean can be handled by Solidity's value types, real-world contracts demand more complex data structures: lists of token holders, nested records of user positions, lookup tables that map addresses to permissions. These needs are served by reference types.
Reference types are fundamentally different from value types in how they store, copy, and pass data. Misunderstanding this difference is one of the most common sources of bugs in Solidity — bugs that can be silent, subtle, and devastatingly expensive on a live blockchain. This article provides a thorough technical exploration of all four Solidity reference types: fixed-size arrays, dynamic arrays, structs, and mappings. We will examine how each works internally, how the critical concept of data location governs their behavior, and how to use them correctly and efficiently in production smart contracts.
Value Types vs. Reference Types — A Foundation
Before examining reference types individually, it is essential to understand the fundamental distinction that separates them from value types.
Value Types: Independent Copies
A value type stores its data directly within the variable itself. When you assign one value-type variable to another, the entire value is copied. After the copy, the two variables are completely independent — modifying one has no effect on the other. Solidity's eight value types are: signed integers (int), unsigned integers (uint), booleans (bool), fixed-point numbers (fixed/ufixed), addresses (address), fixed-size byte arrays (bytes1 through bytes32), literals, enums, and contract/function types.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract ValueTypeBehavior {
function demonstrateCopy() public pure returns (uint256, uint256) {
uint256 original = 42;
uint256 copy = original; // Full, independent copy
copy = 100; // Modifying copy does NOT touch original
return (original, copy); // Returns (42, 100)
}
}
Reference Types: Shared Pointers to Data
A reference type does not store its data inline within the variable. Instead, the variable holds a reference (essentially a pointer) to a location in memory, storage, or calldata where the actual data resides. This has a profound implication: assigning one reference-type variable to another may create a shared reference rather than an independent copy. Both variables then point to the same underlying data, and modifications through one are visible through the other.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract ReferenceTypeBehavior {
uint256[] private data;
function demonstrateSharedReference() public returns (uint256) {
data.push(10);
data.push(20);
data.push(30);
// 'ref' points to the SAME storage location as 'data'
uint256[] storage ref = data;
ref[0] = 999; // This modifies data[0]
return data[0]; // Returns 999, NOT 10
}
}
This shared-reference behavior is not a bug — it is by design, and it is what makes reference types powerful. But it also makes them dangerous when misunderstood. Whether an assignment creates a shared reference or an independent copy depends entirely on the data location of the variables involved.
Data Locations: The Core of Reference Type Behavior
Data location is the single most important concept for understanding reference types in Solidity. Every reference-type variable must have an associated data location, and that location determines how the variable behaves during assignment, how much gas operations cost, and whether data persists after a function call.
Solidity has three data locations:
storage
Storage is the persistent, on-chain data layer. It is where all state variables live. Data written to storage persists across function calls and transactions — it is the permanent record of the contract's state.
Storage is organized as a key-value store mapping 256-bit slots to 256-bit values. It is by far the most expensive data location to read from and write to. Writing a fresh storage slot costs 20,000 gas; updating an existing one costs 5,000 gas; reading costs 2,100 gas (cold) or 100 gas (warm, i.e., already accessed in the same transaction).
memory
Memory is a temporary, byte-addressable area that exists only for the duration of a single external function call. It is freshly allocated when a function is called and completely erased when the function returns. Memory is linear (like a byte array) and can be expanded as needed, though expansion costs gas quadratically.
Memory reads and writes are significantly cheaper than storage: 3 gas per read or write to already-allocated memory.
calldata
Calldata is a read-only, temporary area that contains the input data of an external function call. It is the cheapest location to read from because the data is already encoded in the transaction and requires no copying. Calldata variables cannot be modified — they are immutable by design.
Assignment Rules Between Locations
The interaction between data locations during assignment is where most confusion (and bugs) arise. Here are the definitive rules:
| From → To | Behavior |
storage → storage (local variable) | Creates a reference (shared pointer). Changes through one affect the other. |
storage → memory | Creates an independent copy. Changes to the memory copy do not affect storage. |
memory → memory | Creates a reference (shared pointer) for complex types like structs and arrays. |
memory → storage | Creates an independent copy into storage. |
calldata → memory | Creates an independent copy. |
calldata → storage | Creates an independent copy into storage. |
calldata → calldata (local variable) | Creates a reference (shared pointer). |
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract DataLocationDemo {
uint256[] public storageArray;
constructor() {
storageArray.push(1);
storageArray.push(2);
storageArray.push(3);
}
// storage → storage: SHARED REFERENCE
function storageToStorage() public returns (uint256) {
uint256[] storage ref = storageArray;
ref[0] = 999;
return storageArray[0]; // Returns 999 — same data
}
// storage → memory: INDEPENDENT COPY
function storageToMemory() public view returns (uint256, uint256) {
uint256[] memory copy = storageArray;
copy[0] = 888;
return (storageArray[0], copy[0]); // (original value, 888)
}
// calldata → memory: INDEPENDENT COPY
function calldataToMemory(
uint256[] calldata input
) public pure returns (uint256) {
uint256[] memory copy = input;
copy[0] = 777;
// input[0] is unchanged — calldata is read-only
return input[0]; // Returns original value
}
// memory → memory: REFERENCE for arrays and structs
function memoryToMemory() public pure returns (uint256) {
uint256[] memory a = new uint256[](3);
a[0] = 10;
a[1] = 20;
a[2] = 30;
uint256[] memory b = a; // b references the SAME memory
b[0] = 500;
return a[0]; // Returns 500 — shared reference
}
}
Understanding these rules is not optional — it is the foundation upon which correct use of every reference type rests.
Fixed-Size Arrays
Definition
A fixed-size array is an array whose length is determined at compile time and cannot change after deployment. The size is declared as part of the type itself.
uint256[5] public scores; // Exactly 5 elements of type uint256
address[3] public admins; // Exactly 3 addresses
bool[10] private flags; // Exactly 10 boolean flags
Properties and Behavior
Fixed-size arrays have several distinctive characteristics:
Length is constant. You cannot push to or pop from a fixed-size array. The
.push()and.pop()methods are not available.Length is accessible. The
.lengthproperty returns the compile-time size.Default values. All elements are initialized to the default value of their element type (0 for
uint256,address(0)foraddress, etc.).Can be declared in any data location. Fixed-size arrays can exist in storage, memory, and calldata.
Declaration and Initialization
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract FixedArrayDemo {
// State variable: lives in storage
uint256[5] public highScores;
// Nested fixed arrays
uint256[3][2] public matrix; // 2 arrays, each containing 3 elements
// NOTE: Solidity array notation is REVERSED compared to most languages.
// uint256[3][2] means: an array of 2 elements, each of type uint256[3]
// Access: matrix[outerIndex][innerIndex]
function initializeScores() public {
highScores[0] = 100;
highScores[1] = 95;
highScores[2] = 88;
highScores[3] = 72;
highScores[4] = 65;
// highScores[5] = 50; // Would revert: index out of bounds
}
// Fixed arrays in memory
function createInMemory() public pure returns (uint256) {
uint256[4] memory temp;
temp[0] = 10;
temp[1] = 20;
temp[2] = 30;
temp[3] = 40;
return temp[2]; // Returns 30
}
// Fixed arrays as function parameters
function sumArray(uint256[3] calldata values) external pure returns (uint256) {
uint256 total = 0;
for (uint256 i = 0; i < values.length; i++) {
total += values[i];
}
return total;
}
// Returning fixed arrays from functions
function getTopThree() public view returns (uint256[3] memory) {
return [highScores[0], highScores[1], highScores[2]];
}
}
When to Use Fixed-Size Arrays
Fixed-size arrays are ideal when the number of elements is known at compile time and will never change. Common use cases include:
Role-based access — A fixed set of admin addresses (e.g., a 3-of-5 multisig).
Configuration constants — A set of fee tiers, threshold values, or protocol parameters.
Game state — A tic-tac-toe board (
uint8[3][3]), a chess board, or a fixed hand of cards.Cryptographic operations — Fixed-size inputs to hash functions or signature verification.
Limitations
Fixed-size arrays cannot grow or shrink. If you attempt to access an index beyond the declared size, the transaction reverts with a panic error. If you need a collection whose size can change at runtime, you must use a dynamic array.
Dynamic Arrays
Definition
A dynamic array is an array whose length can change at runtime. Elements can be added with .push() and removed with .pop(). Dynamic arrays are one of the most frequently used data structures in Solidity.
uint256[] public values; // Dynamic array of uint256
address[] private participants; // Dynamic array of addresses
bytes public rawData; // Special case: dynamic byte array
Note: bytes is a dynamically-sized byte array and is functionally similar to byte[], but it is more tightly packed in storage and calldata, making it cheaper to use. string is essentially a bytes array that is UTF-8 encoded. Both bytes and string are reference types.
Core Operations
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract DynamicArrayDemo {
uint256[] public numbers;
// --- Push: Add element to the end ---
function addNumber(uint256 value) public {
numbers.push(value);
// numbers.length increases by 1
}
// Push with no argument returns a reference to the new element
function addDefault() public {
// Creates a new element with default value (0) and returns a reference
numbers.push(); // Appends 0
}
// --- Pop: Remove last element ---
function removeLast() public {
require(numbers.length > 0, "Array is empty");
numbers.pop();
// numbers.length decreases by 1
// The removed element's storage slot is cleared (gas refund)
}
// --- Length ---
function getLength() public view returns (uint256) {
return numbers.length;
}
// --- Delete: Reset element to default (does NOT shrink array) ---
function resetElement(uint256 index) public {
require(index < numbers.length, "Index out of bounds");
delete numbers[index]; // Sets numbers[index] to 0
// IMPORTANT: Array length is unchanged. The slot still exists.
}
// --- Creating dynamic arrays in memory ---
function createInMemory() public pure returns (uint256[] memory) {
// Memory dynamic arrays must be created with 'new' and a fixed size
// They CANNOT be resized after creation (no push/pop in memory)
uint256[] memory temp = new uint256[](3);
temp[0] = 10;
temp[1] = 20;
temp[2] = 30;
// temp.push(40); // COMPILE ERROR: push is only for storage arrays
return temp;
}
// --- Returning storage arrays ---
function getAllNumbers() public view returns (uint256[] memory) {
// This copies the ENTIRE storage array into memory and returns it.
// WARNING: If the array is large, this can be very expensive.
return numbers;
}
}
How Dynamic Arrays Are Stored On-Chain
Understanding the storage layout of dynamic arrays is critical for both gas optimization and security:
The length of the array is stored at the slot determined by the variable's declaration position (e.g., slot
pfor the first state variable).The elements are stored starting at slot
keccak256(p). Elementiis at slotkeccak256(p) + i(for types that occupy a full slot, likeuint256).
This design means that dynamic array elements are scattered far from the length slot in the storage address space, which has implications for storage collision analysis and proxy contracts.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract ArrayStorageLayout {
uint256[] public data; // length stored at slot 0
function demonstrate() public {
data.push(111);
data.push(222);
data.push(333);
// data.length is at slot 0
// data[0] is at keccak256(abi.encode(0)) + 0
// data[1] is at keccak256(abi.encode(0)) + 1
// data[2] is at keccak256(abi.encode(0)) + 2
}
// Helper to show the actual storage slot for element at a given index
function getElementSlot(uint256 index) public pure returns (bytes32) {
bytes32 baseSlot = keccak256(abi.encode(uint256(0)));
return bytes32(uint256(baseSlot) + index);
}
}
Common Pattern: Remove Element by Swapping
Removing an element from the middle of an array is a notoriously expensive operation in Solidity because shifting all subsequent elements costs O(n) gas. The standard pattern is to swap the target element with the last element, then pop:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract ArrayRemoval {
uint256[] public items;
/// @notice Remove an element by swapping with the last element
/// @dev O(1) gas but does NOT preserve order
function removeUnordered(uint256 index) public {
require(index < items.length, "Index out of bounds");
// Move the last element into the position being removed
items[index] = items[items.length - 1];
// Remove the (now duplicated) last element
items.pop();
}
/// @notice Remove an element while preserving order
/// @dev O(n) gas — expensive for large arrays. Avoid if possible.
function removeOrdered(uint256 index) public {
require(index < items.length, "Index out of bounds");
for (uint256 i = index; i < items.length - 1; i++) {
items[i] = items[i + 1];
}
items.pop();
}
}
The delete Keyword vs. .pop()
A common source of confusion is the difference between delete and .pop():
delete array[i]resets the element at indexito its default value (e.g.,0foruint256) but does not change the array's length. The slot still exists; it just holds the zero value.array.pop()removes the last element, decreases the length by one, and clears the storage slot (potentially earning a gas refund).
contract DeleteVsPop {
uint256[] public data; // [10, 20, 30]
function useDelete() public {
// After: data = [10, 0, 30], length = 3
delete data[1];
}
function usePop() public {
// After: data = [10, 20], length = 2
data.pop();
}
}
Structs
Definition
A struct is a user-defined composite type that groups multiple related fields into a single logical unit. Each field can be any type — value types, other reference types, or even other structs (with certain restrictions). Structs are Solidity's equivalent of records, classes (without methods), or plain data objects in other languages.
struct User {
address wallet;
uint256 balance;
uint64 joinedAt;
bool isActive;
string name;
}
Declaration and Usage
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract StructDemo {
// --- Struct Definition ---
struct Employee {
address wallet;
uint128 salary;
uint64 startDate;
uint32 departmentId;
bool active;
string name;
}
// --- State Variables Using Structs ---
Employee[] public employees;
mapping(address => Employee) public employeeByAddress;
// --- Creating Structs ---
function addEmployee(
address wallet,
uint128 salary,
string calldata name,
uint32 departmentId
) external {
// Method 1: Positional constructor
Employee memory emp1 = Employee(
wallet,
salary,
uint64(block.timestamp),
departmentId,
true,
name
);
// Method 2: Named fields (preferred — more readable, order-independent)
Employee memory emp2 = Employee({
wallet: wallet,
salary: salary,
startDate: uint64(block.timestamp),
departmentId: departmentId,
active: true,
name: name
});
// Method 3: Direct storage assignment (no memory intermediate)
employees.push(); // Creates a new element with default values
uint256 index = employees.length - 1;
Employee storage newEmp = employees[index];
newEmp.wallet = wallet;
newEmp.salary = salary;
newEmp.startDate = uint64(block.timestamp);
newEmp.departmentId = departmentId;
newEmp.active = true;
newEmp.name = name;
// Store in mapping as well
employeeByAddress[wallet] = emp2;
}
// --- Reading Struct Fields ---
function getEmployeeSalary(uint256 index) external view returns (uint128) {
return employees[index].salary;
}
// --- Modifying Structs via Storage Reference ---
function deactivateEmployee(uint256 index) external {
// This creates a REFERENCE to the storage struct
Employee storage emp = employees[index];
emp.active = false;
// The change persists because emp points to storage
}
// --- Caution: Memory Copy Does Not Persist ---
function failedUpdate(uint256 index) external view {
// This creates a COPY in memory
Employee memory emp = employees[index];
emp.active = false;
// This change is LOST when the function returns
// The storage data is unchanged
}
}
Struct Storage Layout and Packing
Structs follow the same storage packing rules as regular state variables. Fields are packed into 256-bit slots sequentially, and smaller types declared consecutively can share a slot.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract StructPacking {
// POORLY ORDERED: 4 storage slots
struct Wasteful {
uint8 status; // Slot 0: 8 bits (248 bits wasted)
uint256 amount; // Slot 1: 256 bits (full slot)
uint8 category; // Slot 2: 8 bits (248 bits wasted)
address owner; // Slot 3: 160 bits (96 bits wasted)
}
// Total: 4 slots × 32 bytes = 128 bytes of storage
// WELL ORDERED: 2 storage slots
struct Efficient {
uint256 amount; // Slot 0: 256 bits (full slot — must be alone)
address owner; // Slot 1: 160 bits
uint8 status; // Slot 1: +8 bits (total: 168)
uint8 category; // Slot 1: +8 bits (total: 176)
// 80 bits remaining in Slot 1
}
// Total: 2 slots × 32 bytes = 64 bytes of storage (50% reduction!)
}
The difference between these two layouts is not academic. Every storage slot read or written costs gas. A contract that manages thousands of structs can save enormous amounts of gas — and therefore real money — by ordering fields to minimize slot usage.
Nested Structs
Structs can contain other structs, arrays, and mappings, enabling rich data modeling:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract NestedStructs {
struct Address {
string street;
string city;
uint32 zipCode;
}
struct Order {
uint256 orderId;
uint256 totalPrice;
uint64 timestamp;
Address shippingAddress; // Nested struct
uint256[] itemIds; // Dynamic array inside struct
}
mapping(address => Order[]) public userOrders;
function createOrder(
uint256 orderId,
uint256 totalPrice,
string calldata street,
string calldata city,
uint32 zipCode,
uint256[] calldata itemIds
) external {
Order storage newOrder = userOrders[msg.sender].push();
newOrder.orderId = orderId;
newOrder.totalPrice = totalPrice;
newOrder.timestamp = uint64(block.timestamp);
newOrder.shippingAddress = Address(street, city, zipCode);
for (uint256 i = 0; i < itemIds.length; i++) {
newOrder.itemIds.push(itemIds[i]);
}
}
}
Important restriction: A struct cannot contain a member of its own type directly (no recursive structs), but it can contain a mapping or dynamic array that references its own type indirectly. For example, a mapping(uint256 => Node) inside a Node struct is valid and is the standard pattern for on-chain linked lists and trees.
Mappings
Definition
A mapping is a hash-table-like data structure that associates keys with values. It is declared with the syntax mapping(KeyType => ValueType). Mappings are arguably the most important reference type in Solidity — they are the backbone of virtually every non-trivial smart contract.
mapping(address => uint256) public balances;
mapping(uint256 => string) public tokenNames;
mapping(address => mapping(address => uint256)) public allowances; // Nested mapping
Key Constraints
The key type must be a value type: uint256, int256, address, bool, bytes32, an enum, or a contract type. You cannot use reference types (arrays, structs, mappings) as keys.
The value type can be anything: value types, arrays, structs, or even other mappings.
Fundamental Properties
Mappings have several properties that distinguish them from arrays and hash maps in other languages:
No iteration. Mappings do not support iterating over keys. There is no
.length, no.keys(), no way to enumerate entries. If you need to iterate, you must maintain a separate array of keys alongside the mapping.No deletion tracking. The
deletekeyword resets a mapping entry to its default value, but there is no way to distinguish between "this key was deleted" and "this key was never set" — both return the default value.Every key maps to a value. A mapping conceptually has an entry for every possible key. Accessing a key that was never explicitly set returns the default value for the value type (0,
address(0),false, empty string, etc.).Storage only. Mappings can only be declared as state variables (storage). They cannot exist in memory or calldata.
How Mappings Are Stored
The storage slot for a value in a mapping is computed as: keccak256(abi.encode(key, slot)), where slot is the storage slot number of the mapping variable itself. This means values are scattered across the vast 2²⁵⁶ storage address space, making collisions effectively impossible.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract MappingStorage {
mapping(address => uint256) public balances; // Slot 0
function getStorageSlot(address key) public pure returns (bytes32) {
// The value for 'key' is stored at this computed slot
return keccak256(abi.encode(key, uint256(0)));
}
}
For nested mappings like mapping(address => mapping(address => uint256)), the computation chains: the inner mapping's slot is first computed from the outer key and the outer mapping's slot, then the final value's slot is computed from the inner key and the inner mapping's slot.
Practical Mapping Patterns
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract MappingPatterns {
// --- Basic Mapping ---
mapping(address => uint256) public balances;
// --- Nested Mapping (ERC-20 Allowances) ---
mapping(address => mapping(address => uint256)) public allowances;
// --- Mapping to Struct ---
struct UserProfile {
string username;
uint256 reputation;
uint64 registeredAt;
bool exists; // Flag to distinguish "not found" from "default values"
}
mapping(address => UserProfile) public profiles;
// --- Mapping to Array ---
mapping(address => uint256[]) public userTransactions;
// --- Iterable Mapping Pattern ---
// Since mappings cannot be iterated, maintain a parallel array of keys
address[] public allUsers;
mapping(address => bool) private isRegistered;
function register(string calldata username) external {
require(!isRegistered[msg.sender], "Already registered");
profiles[msg.sender] = UserProfile({
username: username,
reputation: 0,
registeredAt: uint64(block.timestamp),
exists: true
});
allUsers.push(msg.sender);
isRegistered[msg.sender] = true;
}
function getUserCount() external view returns (uint256) {
return allUsers.length;
}
// Now we can iterate over all users
function getTotalReputation() external view returns (uint256 total) {
for (uint256 i = 0; i < allUsers.length; i++) {
total += profiles[allUsers[i]].reputation;
}
}
// --- Existence Check Pattern ---
function getProfile(
address user
) external view returns (UserProfile memory) {
require(profiles[user].exists, "User not found");
return profiles[user];
}
// --- Delete Pattern ---
function deleteProfile(address user) external {
require(profiles[user].exists, "User not found");
delete profiles[user]; // Resets all fields to defaults (exists becomes false)
// Note: user remains in allUsers array — complete removal requires
// additional logic (swap-and-pop, or a "deleted" flag)
}
}
Mapping Limitations and Workarounds
The inability to iterate over mappings is one of Solidity's most discussed limitations. Here is a robust iterable mapping implementation:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
/// @title Iterable Mapping Library
/// @notice Provides O(1) insert, O(1) lookup, O(1) delete, and O(n) iteration
contract IterableMapping {
struct Map {
address[] keys;
mapping(address => uint256) values;
mapping(address => uint256) indexOf; // key → index in keys array
mapping(address => bool) exists;
}
Map private map;
function set(address key, uint256 value) public {
if (map.exists[key]) {
// Update existing entry
map.values[key] = value;
} else {
// Insert new entry
map.exists[key] = true;
map.values[key] = value;
map.indexOf[key] = map.keys.length;
map.keys.push(key);
}
}
function remove(address key) public {
if (!map.exists[key]) return;
delete map.exists[key];
delete map.values[key];
// Swap with last element and pop (O(1) removal)
uint256 index = map.indexOf[key];
address lastKey = map.keys[map.keys.length - 1];
map.keys[index] = lastKey;
map.indexOf[lastKey] = index;
map.keys.pop();
delete map.indexOf[key];
}
function get(address key) public view returns (uint256) {
require(map.exists[key], "Key not found");
return map.values[key];
}
function size() public view returns (uint256) {
return map.keys.length;
}
function getKeyAtIndex(uint256 index) public view returns (address) {
return map.keys[index];
}
}
Reference Types and Gas Optimization
Gas efficiency is a central concern in smart contract development. Reference types, because they often interact with storage, are the primary targets for gas optimization.
Cost Comparison by Data Location
| Operation | Storage (cold) | Storage (warm) | Memory | Calldata |
| Read | 2,100 gas | 100 gas | 3 gas | 3 gas |
| Write | 20,000 gas (new) / 5,000 gas (update) | 5,000 / 100 gas | 3 gas | N/A (read-only) |
Optimization Strategies
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract GasOptimization {
struct UserData {
uint256 balance;
uint256 totalDeposits;
uint256 lastAction;
}
mapping(address => UserData) public users;
// BAD: Multiple storage reads
function inefficientRead(address user) external view returns (uint256) {
// Each access to users[user] is a separate storage read
uint256 result = users[user].balance
+ users[user].totalDeposits
+ users[user].lastAction;
return result;
}
// GOOD: Cache struct in memory, read storage once
function efficientRead(address user) external view returns (uint256) {
UserData memory data = users[user]; // Single storage read (copies all fields)
return data.balance + data.totalDeposits + data.lastAction;
}
// BAD: Unnecessary memory copy when only modifying one field
function inefficientWrite(address user) external {
UserData memory data = users[user]; // Reads ALL fields from storage
data.lastAction = block.timestamp;
users[user] = data; // Writes ALL fields back to storage
}
// GOOD: Direct storage reference for targeted modifications
function efficientWrite(address user) external {
users[user].lastAction = block.timestamp; // Single SSTORE
}
// GOOD: Use calldata for read-only function parameters
function processIds(uint256[] calldata ids) external pure returns (uint256) {
// calldata is cheapest — no copying
uint256 sum = 0;
for (uint256 i = 0; i < ids.length; i++) {
sum += ids[i];
}
return sum;
}
// LESS EFFICIENT: memory parameter forces a copy from calldata
function processIdsMemory(uint256[] memory ids) public pure returns (uint256) {
uint256 sum = 0;
for (uint256 i = 0; i < ids.length; i++) {
sum += ids[i];
}
return sum;
}
}
Key Gas Rules for Reference Types
Use
calldatafor read-only function parameters. If a function does not modify an array or struct parameter, declare it ascalldatainstead ofmemoryto avoid an unnecessary copy.Cache storage reads in memory. If you read multiple fields from the same storage struct or read the same storage variable multiple times, copy it to a memory variable first.
Use storage references for targeted writes. If you only need to modify one or two fields of a storage struct, use a
storagereference to write directly, rather than copying the entire struct to memory and back.Pack struct fields for storage efficiency. Order fields by size to minimize the number of storage slots used.
Avoid returning large arrays from view functions. Copying a large storage array into memory is expensive even in a view call (it still costs gas when called externally from another contract). Consider pagination or off-chain indexing for large data sets.
Practical Use Cases: Reference Types in Real Smart Contracts
Use Case 1: NFT Marketplace
This example demonstrates how arrays, structs, and mappings work together in a realistic contract:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract NFTMarketplace {
struct Listing {
address seller;
address nftContract;
uint256 tokenId;
uint128 price; // Packed with expiry in a single slot
uint64 expiry;
uint32 listingId;
bool active;
}
// --- Mappings for O(1) lookups ---
// listingId => Listing
mapping(uint256 => Listing) public listings;
// nftContract => tokenId => listingId (find listing for a specific NFT)
mapping(address => mapping(uint256 => uint256)) public nftToListing;
// seller => listingId[] (all listings by a specific seller)
mapping(address => uint256[]) public sellerListings;
// --- State ---
uint256 public nextListingId;
uint256[] public activeListingIds; // Dynamic array for iteration
// --- Events ---
event Listed(uint256 indexed listingId, address indexed seller, uint128 price);
event Sold(uint256 indexed listingId, address indexed buyer, uint128 price);
event Cancelled(uint256 indexed listingId);
function list(
address nftContract,
uint256 tokenId,
uint128 price,
uint64 duration
) external returns (uint256) {
require(price > 0, "Price must be positive");
uint256 listingId = nextListingId++;
// Write to mapping (storage)
listings[listingId] = Listing({
seller: msg.sender,
nftContract: nftContract,
tokenId: tokenId,
price: price,
expiry: uint64(block.timestamp) + duration,
listingId: uint32(listingId),
active: true
});
// Update index mappings
nftToListing[nftContract][tokenId] = listingId;
sellerListings[msg.sender].push(listingId);
activeListingIds.push(listingId);
emit Listed(listingId, msg.sender, price);
return listingId;
}
function buy(uint256 listingId) external payable {
// Use storage reference for efficient read + write
Listing storage item = listings[listingId];
require(item.active, "Not active");
require(block.timestamp <= item.expiry, "Expired");
require(msg.value >= item.price, "Insufficient payment");
item.active = false; // Direct storage write — efficient
// Transfer logic would go here (NFT transfer, payment to seller)
emit Sold(listingId, msg.sender, item.price);
}
function getSellerListingCount(address seller) external view returns (uint256) {
return sellerListings[seller].length;
}
}
Use Case 2: Governance System with Proposals and Votes
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract Governance {
enum ProposalState { Pending, Active, Passed, Rejected, Executed }
struct Proposal {
uint256 id;
address proposer;
string description; // Dynamic string (reference type inside struct)
uint256 forVotes;
uint256 againstVotes;
uint64 startTime;
uint64 endTime;
ProposalState state;
address[] targets; // Dynamic array inside struct
bytes[] calldatas; // Dynamic array of bytes inside struct
}
// --- Storage ---
Proposal[] public proposals;
mapping(uint256 => mapping(address => bool)) public hasVoted;
mapping(address => uint256) public votingPower;
uint256 public constant VOTING_PERIOD = 3 days;
uint256 public constant QUORUM = 1000 ether;
function propose(
string calldata description,
address[] calldata targets,
bytes[] calldata calldatas
) external returns (uint256) {
require(targets.length == calldatas.length, "Length mismatch");
require(votingPower[msg.sender] > 0, "No voting power");
uint256 proposalId = proposals.length;
// Push a new empty struct and populate via storage reference
proposals.push();
Proposal storage p = proposals[proposalId];
p.id = proposalId;
p.proposer = msg.sender;
p.description = description;
p.startTime = uint64(block.timestamp);
p.endTime = uint64(block.timestamp + VOTING_PERIOD);
p.state = ProposalState.Active;
// Copy calldata arrays into storage
for (uint256 i = 0; i < targets.length; i++) {
p.targets.push(targets[i]);
p.calldatas.push(calldatas[i]);
}
return proposalId;
}
function vote(uint256 proposalId, bool support) external {
Proposal storage p = proposals[proposalId];
require(p.state == ProposalState.Active, "Not active");
require(block.timestamp <= p.endTime, "Voting ended");
require(!hasVoted[proposalId][msg.sender], "Already voted");
uint256 power = votingPower[msg.sender];
require(power > 0, "No voting power");
hasVoted[proposalId][msg.sender] = true;
if (support) {
p.forVotes += power;
} else {
p.againstVotes += power;
}
}
function finalize(uint256 proposalId) external {
Proposal storage p = proposals[proposalId];
require(p.state == ProposalState.Active, "Not active");
require(block.timestamp > p.endTime, "Voting not ended");
bool quorumReached = (p.forVotes + p.againstVotes) >= QUORUM;
bool majority = p.forVotes > p.againstVotes;
p.state = (quorumReached && majority)
? ProposalState.Passed
: ProposalState.Rejected;
}
}
Best Practices and Common Pitfalls
1. Always Be Explicit About Data Locations
Solidity requires you to specify data locations for reference-type parameters, return values, and local variables. Never rely on implicit defaults — be explicit about whether you intend storage, memory, or calldata.
// GOOD: Explicit and intentional
function update(uint256[] calldata input) external {
uint256[] storage stored = myArray;
uint256[] memory temp = new uint256[](10);
}
2. Understand When Assignments Copy vs. Reference
The most common bug involving reference types is assuming an assignment creates an independent copy when it actually creates a shared reference, or vice versa.
// BUG: Developer expects modification to persist
function buggyUpdate(uint256 index) public {
Employee memory emp = employees[index]; // COPY, not reference
emp.salary = 100000; // Modifies the copy only
// Storage is unchanged — the update is lost
}
// FIX: Use a storage reference
function correctUpdate(uint256 index) public {
Employee storage emp = employees[index]; // REFERENCE to storage
emp.salary = 100000; // Modifies actual storage
}
3. Avoid Unbounded Loops Over Dynamic Arrays
Any loop that iterates over a dynamic array whose length can grow without bound is a potential denial-of-service vector. If an attacker can make the array long enough, the loop will exceed the block gas limit, making the function uncallable.
// DANGEROUS: If 'users' array grows very large, this function becomes uncallable
function distributeRewards() external {
for (uint256 i = 0; i < users.length; i++) {
// This could exceed block gas limit
payable(users[i]).transfer(reward);
}
}
// SAFER: Use a pull pattern or pagination
mapping(address => uint256) public pendingRewards;
function claimReward() external {
uint256 reward = pendingRewards[msg.sender];
require(reward > 0, "No pending reward");
pendingRewards[msg.sender] = 0;
payable(msg.sender).transfer(reward);
}
4. Use calldata for Read-Only Parameters
When a function parameter is not modified within the function body, declare it as calldata rather than memory. This avoids copying the data from calldata into memory, saving gas.
// Cheaper: no copy
function process(uint256[] calldata data) external pure returns (uint256) { ... }
// More expensive: copies data from calldata to memory
function process(uint256[] memory data) public pure returns (uint256) { ... }
Note: calldata can only be used for external function parameters. For public or internal functions, you must use memory.
5. Use the Existence Flag Pattern for Mappings
Since mappings return default values for non-existent keys, use a boolean exists field to distinguish between "value is the default" and "key was never set":
struct Record {
uint256 value;
bool exists;
}
mapping(bytes32 => Record) public records;
function get(bytes32 key) external view returns (uint256) {
require(records[key].exists, "Record not found");
return records[key].value;
}
6. Be Cautious with delete on Complex Types
The delete keyword resets a variable to its default value. For mappings inside structs, delete does not clear the mapping entries — it only resets the simple fields. This can lead to stale data.
struct Account {
uint256 balance;
mapping(address => bool) authorized;
}
mapping(address => Account) public accounts;
function removeAccount(address user) external {
// WARNING: delete accounts[user] resets balance to 0
// but does NOT clear the authorized mapping entries.
// accounts[user].authorized[someAddress] may still return true!
delete accounts[user];
}
7. Avoid Returning Mappings from Functions
Mappings cannot be returned from functions. If you need to expose mapping data, provide getter functions for individual keys or return arrays of keys alongside a lookup function.
8. Consider Off-Chain Indexing for Complex Queries
Solidity is not a database. If your application needs to filter, sort, or paginate large datasets, use an off-chain indexing service (like The Graph or custom event-based indexers) rather than trying to build query infrastructure on-chain. Emit events to make data available for indexing:
event Transfer(address indexed from, address indexed to, uint256 value);
event UserRegistered(address indexed user, string username, uint256 timestamp);
Events are much cheaper than storage and can be efficiently queried off-chain.
Conclusion
Reference types are the structural backbone of Solidity smart contracts. They enable developers to model complex, real-world data relationships — from token balances and governance proposals to marketplace listings and user profiles — within the constraints of the Ethereum Virtual Machine.
The four reference types each serve a distinct purpose:
Fixed-size arrays provide compile-time safety and predictable gas costs for collections of known size. They are ideal for configuration data, fixed-role systems, and any scenario where the number of elements will never change.
Dynamic arrays offer the flexibility to grow and shrink at runtime. They are essential for managing lists of participants, transaction histories, and any collection whose size depends on user behavior. However, they demand careful attention to gas costs, particularly around iteration and element removal.
Structs enable rich data modeling by grouping related fields into cohesive units. They are the foundation of virtually every data-driven contract. Proper field ordering for storage packing can yield dramatic gas savings when structs are stored on-chain.
Mappings provide O(1) key-value lookups and are the single most-used data structure in Solidity. Their inability to be iterated is a deliberate trade-off for gas efficiency. The iterable mapping pattern — maintaining a parallel array of keys — is the standard workaround when enumeration is required.
Cutting across all four types is the concept of data location: storage, memory, and calldata. Understanding how assignment behaves between these locations — when it creates a copy versus a shared reference — is the single most important skill for writing correct, efficient Solidity code. A misunderstood assignment can silently lose data (modifying a memory copy instead of storage) or unexpectedly mutate shared state (operating on a storage reference when a copy was intended).
By mastering these concepts and applying the best practices outlined in this article — explicit data locations, struct packing, the pull pattern for distributions, existence flags for mappings, and off-chain indexing for complex queries — you will write smart contracts that are not only correct and secure, but gas-efficient and maintainable at scale
