SLOAD (0x54) - Voltaire

This page is a placeholder. All examples on this page are currently AI-generated and are not correct. This documentation will be completed in the future with accurate, tested examples.

Overview

Opcode: 0x54 Introduced: Frontier (EVM genesis) Updated: Berlin (EIP-2929, cold/warm tracking) SLOAD reads a 256-bit value from an account’s persistent storage. The gas cost depends on whether the storage slot was previously accessed in the transaction (warm) or not (cold). This operation is essential for reading contract state: balances, permissions, prices, and any data that must persist across transactions.

Specification

Stack Input:

key (storage slot address)

Stack Output:

value (256-bit value at slot, or 0 if uninitialized)

Gas Cost:

100 gas - Warm access (already accessed in transaction)
2100 gas - Cold access (first access, EIP-2929)

Operation:

slot = pop()
value = storage[msg.sender][slot]  // 0 if slot never written
push(value)

Behavior

SLOAD retrieves the current value stored at a key in the calling contract’s account storage:

Pop key from stack (256-bit unsigned integer)
Query host for storage value at contract address + key
Return value from host (0 if slot never written or cleared)
Push result to stack
Track access for cold/warm metering (EIP-2929)
Increment PC

Cold vs Warm Access

First access in transaction (cold): 2100 gas

SLOAD(key)  // 2100 gas - cold access, not yet seen

Subsequent accesses (warm): 100 gas

SLOAD(key)  // 2100 gas first time
SLOAD(key)  // 100 gas second time (warm)

Access list (EIP-2930): Can pre-warm slots

// Access list declaration in transaction
[{ address: contract, storageKeys: [key] }]
// SLOAD uses warm cost even on first access

Uninitialized Slots

Slots never written return 0:

SLOAD(0xFFFFFFFF)  // Returns 0 (never written)

Examples

Basic Storage Read

import { sload } from '@voltaire/evm/storage';
import { createFrame } from '@voltaire/evm/Frame';
import { createMemoryHost } from '@voltaire/evm/Host';

const host = createMemoryHost();
const frame = createFrame({
  stack: [0x42n],  // Key to read
  gasRemaining: 3000n,
  address: contractAddr,
});

// Pre-populate storage
host.setStorage(contractAddr, 0x42n, 0x1337n);

// Execute SLOAD
const error = sload(frame, host);

console.log(frame.stack);        // [0x1337n]
console.log(frame.gasRemaining); // 2900n (3000 - 100 warm)
console.log(error);              // null

Cold Access Tracking

const host = createMemoryHost();
host.setStorage(contractAddr, 0x42n, 0x1337n);
host.setStorage(contractAddr, 0x43n, 0x2222n);

// First access to slot 0x42 (cold)
let frame = createFrame({
  stack: [0x42n],
  gasRemaining: 3000n,
  address: contractAddr,
});
sload(frame, host);
console.log(frame.gasRemaining);  // 900n (3000 - 2100 cold)

// Second access to slot 0x42 (warm, cached)
frame = createFrame({
  stack: [0x42n],
  gasRemaining: 3000n,
  address: contractAddr,
});
sload(frame, host);
console.log(frame.gasRemaining);  // 2900n (3000 - 100 warm)

// First access to slot 0x43 (cold, different slot)
frame = createFrame({
  stack: [0x43n],
  gasRemaining: 3000n,
  address: contractAddr,
});
sload(frame, host);
console.log(frame.gasRemaining);  // 900n (3000 - 2100 cold)

Mapping Access

// Smart contract mapping
mapping(address => uint256) public balances;

// Reading mapping[addr]
// Solidity computes: keccak256(abi.encode(addr, 1)) → storage slot
// Then SLOAD retrieves value at that slot

function getBalance(address user) public view returns (uint256) {
  return balances[user];  // SLOAD with computed key
}

Nested Structures

// Reading from dynamic storage arrays
// array[index] → SLOAD with computed offset
// Requires: baseSlot + (32 * index) for 32-byte elements

const baseSlot = 5n;  // Array stored at slot 5
const index = 10n;
const storageKey = baseSlot + (32n * index);  // Compute slot

frame = createFrame({
  stack: [storageKey],
  gasRemaining: 3000n,
  address: contractAddr,
});
sload(frame, host);

Gas Cost

Cost Matrix:

Access Type	Gas	EIP	Notes
Warm	100	EIP-2929	Seen before in transaction
Cold	2100	EIP-2929	First access in transaction
Pre-warmed	100	EIP-2930	Via access list

Optimization: SLOAD is ~21x more expensive on cold access. Batch accesses or use access lists for known storage reads.

Edge Cases

Uninitialized Slot

const frame = createFrame({
  stack: [0xDEADBEEFn],
  gasRemaining: 3000n,
  address: contractAddr,
});

// Slot never written - returns 0
sload(frame, host);
console.log(frame.stack);  // [0n]

Max Uint256 Value

const MAX = (1n << 256n) - 1n;
host.setStorage(contractAddr, 0x1n, MAX);

const frame = createFrame({
  stack: [0x1n],
  gasRemaining: 3000n,
  address: contractAddr,
});

sload(frame, host);
console.log(frame.stack);  // [MAX]

Stack Boundaries

// Reading with key = 0
const frame = createFrame({
  stack: [0n],  // Slot 0
  gasRemaining: 3000n,
  address: contractAddr,
});
sload(frame, host);

// Reading with key = max
const maxFrame = createFrame({
  stack: [(1n << 256n) - 1n],
  gasRemaining: 3000n,
  address: contractAddr,
});
sload(maxFrame, host);

Insufficient Gas

const frame = createFrame({
  stack: [0x42n],
  gasRemaining: 50n,  // < 100 (warm cost)
  address: contractAddr,
});

const error = sload(frame, host);
console.log(error);  // { type: "OutOfGas" }
console.log(frame.pc);  // 0 (unchanged, not executed)

Common Usage

State Variable Access

contract Counter {
  uint256 public count;  // Slot 0

  function getCount() public view returns (uint256) {
    return count;  // SLOAD(0)
  }

  function increment() public {
    count++;  // SLOAD(0) + ADD + SSTORE(0)
  }
}

Mapping Lookups

contract Bank {
  mapping(address => uint256) public balances;

  function getBalance(address user) public view returns (uint256) {
    return balances[user];  // SLOAD with keccak computed key
  }

  function transfer(address to, uint256 amount) public {
    uint256 myBalance = balances[msg.sender];  // SLOAD cold (2100)
    require(myBalance >= amount, "insufficient balance");

    balances[msg.sender] = myBalance - amount;  // SLOAD warm (100)
    balances[to] += amount;
  }
}

Multi-Read Optimization

// Inefficient: Multiple SLOAD cold accesses
function inefficient(address user) public view returns (uint256, uint256, uint256) {
  return (
    balances[user],     // SLOAD cold (2100)
    approved[user],     // SLOAD cold (2100)
    lastUpdate[user]    // SLOAD cold (2100)
  );
}

// Efficient: Cache in memory (MSTORE is cheap)
function efficient(address user) public view returns (uint256, uint256, uint256) {
  uint256 bal = balances[user];     // SLOAD cold (2100)
  uint256 app = approved[user];     // SLOAD cold (2100) - new slot
  uint256 last = lastUpdate[user];  // SLOAD cold (2100) - new slot
  return (bal, app, last);
}

Access List Warm-up

// Solidity: Declare access list in transaction
const tx = {
  to: contractAddr,
  data: encodeFunctionCall("transfer", [to, amount]),
  accessList: [
    {
      address: contractAddr,
      storageKeys: [
        0x0n,  // balances mapping base
        0x1n,  // approved mapping base
      ]
    }
  ]
};

// SLOAD now uses 100 gas (warm) even on first access

Implementation

TypeScript

import * as Frame from "../../Frame/index.js";
import { ColdSload } from "../../../primitives/GasConstants/BrandedGasConstants/constants.js";

/**
 * SLOAD (0x54) - Load word from storage
 *
 * Stack:
 *   in: key
 *   out: value
 *
 * Gas: 100 (warm) or 2100 (cold) - EIP-2929
 */
export function sload(frame, host) {
  // Pop key from stack
  const keyResult = Frame.popStack(frame);
  if (keyResult.error) return keyResult.error;
  const key = keyResult.value;

  // Note: EIP-2929 access list tracking for warm/cold slots
  // For now, assume cold access (worst case)
  const gasCost = ColdSload;

  const gasError = Frame.consumeGas(frame, gasCost);
  if (gasError) return gasError;

  // Load from storage via host
  const value = host.getStorage(frame.address, key);

  // Push value onto stack
  const pushError = Frame.pushStack(frame, value);
  if (pushError) return pushError;

  frame.pc += 1;
  return null;
}

Testing

Test Coverage

import { describe, it, expect } from 'vitest';
import { sload } from './0x54_SLOAD.js';
import { createFrame } from '../../Frame/index.js';
import { createMemoryHost } from '../../Host/createMemoryHost.js';
import { from as addressFrom } from '../../../primitives/Address/index.js';

describe('SLOAD (0x54)', () => {
  it('loads value from storage', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");
    host.setStorage(addr, 0x42n, 0x1337n);

    const frame = createFrame({
      stack: [0x42n],
      gasRemaining: 10000n,
      address: addr,
    });

    expect(sload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([0x1337n]);
    expect(frame.pc).toBe(1);
  });

  it('loads zero for uninitialized storage', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");

    const frame = createFrame({
      stack: [0xFFFFFFFFFn],
      gasRemaining: 10000n,
      address: addr,
    });

    expect(sload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([0n]);
  });

  it('isolates storage by address', () => {
    const host = createMemoryHost();
    const addr1 = addressFrom("0x1111111111111111111111111111111111111111");
    const addr2 = addressFrom("0x2222222222222222222222222222222222222222");

    host.setStorage(addr1, 0x42n, 0xAAAAn);
    host.setStorage(addr2, 0x42n, 0xBBBBn);

    let frame = createFrame({
      stack: [0x42n],
      gasRemaining: 10000n,
      address: addr1,
    });
    expect(sload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([0xAAAAn]);

    frame = createFrame({
      stack: [0x42n],
      gasRemaining: 10000n,
      address: addr2,
    });
    expect(sload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([0xBBBBn]);
  });

  it('consumes 2100 gas on cold access', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");
    host.setStorage(addr, 0x42n, 0x1337n);

    const frame = createFrame({
      stack: [0x42n],
      gasRemaining: 5000n,
      address: addr,
    });

    expect(sload(frame, host)).toBeNull();
    expect(frame.gasRemaining).toBe(2900n);  // 5000 - 2100
  });

  it('returns StackUnderflow on empty stack', () => {
    const host = createMemoryHost();
    const frame = createFrame({
      stack: [],
      gasRemaining: 10000n,
      address: addressFrom("0x1111111111111111111111111111111111111111"),
    });

    expect(sload(frame, host)).toEqual({ type: "StackUnderflow" });
  });

  it('returns OutOfGas when insufficient gas', () => {
    const host = createMemoryHost();
    const frame = createFrame({
      stack: [0x42n],
      gasRemaining: 50n,
      address: addressFrom("0x1111111111111111111111111111111111111111"),
    });

    expect(sload(frame, host)).toEqual({ type: "OutOfGas" });
  });

  it('returns StackOverflow when stack full', () => {
    const host = createMemoryHost();
    const fullStack = new Array(1024).fill(0n);

    const frame = createFrame({
      stack: fullStack,
      gasRemaining: 10000n,
      address: addressFrom("0x1111111111111111111111111111111111111111"),
    });

    expect(sload(frame, host)).toEqual({ type: "StackOverflow" });
  });
});

Security

State Immutability During Reads

SLOAD is read-only and safe in any context (even static calls). It cannot modify state, only query it:

function read(address user) public view returns (uint256) {
  return balances[user];  // Always safe, read-only
}

Reentrancy Vulnerability (When Used with State Changes)

SLOAD itself is safe, but reading and then writing creates reentrancy windows:

// VULNERABLE: Read-check-write pattern
function transfer(address to, uint256 amount) public {
  uint256 balance = balances[msg.sender];  // SLOAD
  require(balance >= amount);

  balances[msg.sender] = balance - amount;  // SSTORE

  (bool ok, ) = to.call("");  // REENTERS HERE
  // Attacker re-enters before balance updated
}

// SAFE: Checks-Effects-Interactions pattern
function transfer(address to, uint256 amount) public {
  require(balances[msg.sender] >= amount);
  balances[msg.sender] -= amount;  // SSTORE first
  (bool ok, ) = to.call("");  // Reenter safely
  require(ok, "transfer failed");
}

Access List Validation

Ensure access lists match actual storage accessed:

// Declared in access list
accessList: [{ address: token, storageKeys: [slot0, slot1] }]

// But code accesses different slot
host.getStorage(token, 0xFF)  // Slot 0xFF not in access list!
// Will cost 2100 gas instead of expected 100

Gas Cost Variation

Cold/warm access affects gas accounting for batch operations:

function batchTransfer(address[] calldata users, uint256[] calldata amounts) public {
  for (uint i = 0; i < users.length; i++) {
    uint256 bal = balances[users[i]];  // Variable cost!
    // First unique user: 2100 gas (cold)
    // Repeated user: 100 gas (warm)
  }
}

Benchmarks

Access cost comparison:

Warm SLOAD: 100 gas
Cold SLOAD: 2100 gas (21x more expensive)
MLOAD (memory): 3 gas (67x cheaper than warm)
L1 cache: ~0.5ns vs ~100ns for cold storage

Practical implications:

// Reading 100 values from same slot
SLOAD(key)  // 2100 gas first time
// Keep in stack/memory (cheap operations)
// 99 more stack operations at 3 gas each ≈ 297 gas total
// Total: 2100 + 297 = 2397 gas

// vs reading from cold storage 100 times
// 100 × 2100 = 210,000 gas (86x more expensive!)

References

EVM Codes - SLOAD (0x54)
EIP-2929: Gas-cost increases for state access opcodes
EIP-2930: Optional access lists
Yellow Paper - Section 9.3 (Account Storage)
Solidity Storage Layout

Documentation Index

​Overview

​Specification

​Behavior

​Cold vs Warm Access

​Uninitialized Slots

​Examples

​Basic Storage Read

​Cold Access Tracking

​Mapping Access

​Nested Structures

​Gas Cost

​Edge Cases

​Uninitialized Slot

​Max Uint256 Value

​Stack Boundaries

​Insufficient Gas

​Common Usage

​State Variable Access

​Mapping Lookups

​Multi-Read Optimization

​Access List Warm-up

​Implementation

​Testing

​Test Coverage

​Security

​State Immutability During Reads

​Reentrancy Vulnerability (When Used with State Changes)

​Access List Validation

​Gas Cost Variation

​Benchmarks

​References

Overview

Specification

Behavior

Cold vs Warm Access

Uninitialized Slots

Examples

Basic Storage Read

Cold Access Tracking

Mapping Access

Nested Structures

Gas Cost

Edge Cases

Uninitialized Slot

Max Uint256 Value

Stack Boundaries

Insufficient Gas

Common Usage

State Variable Access

Mapping Lookups

Multi-Read Optimization

Access List Warm-up

Implementation

Testing

Test Coverage

Security

State Immutability During Reads

Reentrancy Vulnerability (When Used with State Changes)

Access List Validation

Gas Cost Variation

Benchmarks

References