The Storage is one of the four data locations a solidity smart contract has (the others are : memory, calldata and stack). In simple words, it is the “database” associated to the smart contract, values are persisted after the transaction finishes, which is why it contains the contract’s “state” variables.

Storage definition

Each smart contract storage contains (theoretically) 2**256 slots that are 32 bytes long (technically an infinite amount of slots). A slot is kind of the “basic unit” of the storage, when reading or writing from/to the storage we have to deal with slots and not with individual bytes.

Variables visibility

Storage variables (also called “state” variables) can have the following visibility definitions:

It is important to note that storage variables can be read from off-chain applications independently of their visibility definition, “private” variables are not really private….

Storage layout

Variables can be stored on storage in different ways, depending on their data type, the order in which they were defined and sometimes even on their value.

Value types

Value types (uint256, address, bool, …) are stored in the order they are defined.

By default each variable takes one full slot, this can however be a little bit different if its data type is less than 32 bytes long and the previous/next variable is also less than 32 bytes long, in that case, if both variable can fit into a single slot (their combined length is less than or equal to 32 bytes long) solidity packs them.

Fixed size arrays are stored in a similar way, with the only peculiarity that they cannot be packed with any variable defined before or after.

For instance:

uint256 u1; // 32 bytes-long
uint256 u2; // 32 bytes-long
address a1; // 20 bytes-long
bool b1;    // 1 bytes-long
address a2; // 20 bytes-long
bool[5] arr1; // 5 bytes-long
bool b2; // 1 bytes-long

u1 and u2 will take their own slots (slot 0 and slot 1).

a1 and b1 will be packed into a single slot, since their combined length is 21 bytes (slot 2)

a2 will take its own slot too, since it does not fit in the remaining 11 bytes from slot 3 (slot 3).

arr1 will start in a new slot because it is a fix-size array (even if technically it could fit in the previous slots remaining 12 bytes) and its values will be packed (slot 4).

b2 will start in a new slot (despite been only 1 byte, which could fit into the previous slot) because the previous variable was a fix-size array (slot 5).

Reference Types

Reference types are : dynamic-size arrays, mappings and structures.

Bytes & Strings

Bytes and Strings (which are basically fancy bytes) storage policy depends on their size.

Value: stored in the higher-order bytes (left aligned).
Length: stored in the lowest-order byte (rightmost byte) as length * 2.

Inheritance

The solidity compiler accepts multiple inheritance and uses the C3 linearization algorithm (beyond the scope of this blog) to determine the final “linear” hierarchy of parent smart contracts.

State variables defined in parent smart contracts get inherited by their children to form the final storage layout, the order of those variable is determined by the C3 linearization algorithm result.

contract parent_1
{
  uint256 p1_u;
  address p1_a;
}

contract parent_2
{
  uint256 p2_u;
  address p2_a;
}

contract child is parent_1, parent_2
{
  uint256 u;
  address a;
}

// FINAL STORAGE LAYOUT FOR "child":

uint256 p1_u; // Slot 0
address p1_a; // Slot 1
uint256 p2_u; // Slot 2
address p2_a; // Slot 3
uint256 u;    // Slot 4
address a;    // Slot 5

This is very important to keep in mind when upgrading smart contracts (using transparent proxies or any other pattern) because if we add state variables to parent contracts, or new contracts with state variables to the inheritance, those new state variables might “shift” down the previous ones which may lead to undesired and unexpected consequences.

contract parent_3
{
  uint256 p3_u;
  address p3_a;
}

contract child is parent_1, parent_2, parent-3
{
  uint256 u;
  address a;
}

// FINAL STORAGE LAYOUT FOR "child":

uint256 p1_u; // Slot 0
address p1_a; // Slot 1
uint256 p2_u; // Slot 2
address p2_a; // Slot 3
uint256 p3_u; // Slot 4 : p3_u will contain the value u had
address p3_a; // Slot 5 : p3_a will contain the value a had
uint256 u;    // Slot 6 : u will be 0
address a;    // Slot 7 : a will be 0x

Gas cost

Saving data in storage means saving data on the blockchain forever (or until you remove it) which is why dealing with storage in ethereum is very expensive in terms of gas.

Removing data from storage on the other hand allows for some transaction gas to be refunded, this is done to encourage developers to “release” storage that is not needed anymore.

Another important Gas related policy to keep in mind when dealing with storage is the concept of “cold and warm” accesses. Since EIP-2929, the EVM makes the difference between the first time we access a storage variable within a transaction (cold access, it does not matter if it is a read or write access) and the rest (warm access):

/* Disclaimer : this code is only to illustrate the gas costs, 
 it does not make much sense for itself... */

uint256 _u1;

function gasCostRead() external returns (uint256)
{
  uint256 uCold = _u1; // Cold Read : Sload = 2'100 gas
  uint256 uWarm = _u1; // Warm Read : Sload = 100 gas
  retun u1;
}

function gasCostWrite() external
{
  _u1 = 3; /* Cold Write : Sstore = 22'100 gas (if _u1 was 0), 
                                    5'000 gas (if _u1 was neither 0 nor 3
                                    2'200 (if _u1 was 3) */
  _u1 = 4; // Warm Write : Sstore = 2'900 gas because _u1 was 3 
  _u1 = 4; // Warm Write : Sstore = 100 gas because _u1 was 4 already
  _u1 = 0; // Warm Write : Sstore = 2'900 gas because _u1 was 4 + 20% refund (max 4'800 gas)
  _u1 = 3; // Warm Write : Sstore = 20'000 gas because _u1 was 0
}

Best Practices

When dealing with storage variables