EIP-8125 Temporary contract storage

No call decision · EVM & execution · EIP status Draft · created 2026-01-14

Adds a temporary storage that persists across transactions and blocks but is automatically cleared by the protocol once a set period has passed. It is written with the new TMPSTORE opcode and read with TMPLOAD.

Why it is needed

Right now contracts effectively have only two ways to store data. Writing to persistent storage means every node must keep holding that data on disk, which increases the long-term burden on the whole network. Transient storage (EIP-1153), on the other hand, disappears as soon as a single transaction ends, so it cannot be used across multiple transactions. Yet according to the source material, more than 60% of all storage slots are written once and never accessed on-chain again. Data that is only needed briefly still ends up in persistent storage, continually bloating state. This EIP creates that middle ground. It provides storage that persists for a set period and is then automatically cleared, so this kind of state does not pile up indefinitely even without developers deleting it themselves.

What changes

Today

After EIP-8125

Who is affected

In depth

Data model: two reserved system accounts

Temporary storage is backed by two reserved system accounts, TEMP_STORAGE_SYSTEM_ADDRESS_0 and TEMP_STORAGE_SYSTEM_ADDRESS_1. The key space is a (contract_address, key) -> value mapping, and the actual slot key is derived as derived_slot_key = keccak256(contract_address || key). The value is stored under this slot key in the system account's ordinary storage trie. In other words, no separate new data structure is created; the existing account storage structure is reused as is, and per-contract isolation is guaranteed by mixing the contract address into the hash.

Periodic rollover: reset by clearing a single storageRoot

For blocks after activation, the period is determined by period_index(block_number) = floor((block_number - FORK_BLOCK) / TEMP_STORAGE_PERIOD), and the two system accounts alternately take on the current (CURRENT_SYSADDR) and previous (PREVIOUS_SYSADDR) roles according to current_index = period_index % 2. If block B's period_index is greater than parent block P's, the protocol MUST set CURRENT_SYSADDR.storageRoot = EMPTY_TRIE_ROOT before executing B's transactions, clearing the new current account. No other account is touched. As a result, entries written in the immediately preceding period can still be read for one more period via the previous account, while older entries are removed.

Behavior of TMPLOAD and TMPSTORE

TMPLOAD(key) computes the derived_slot_key, reads first from CURRENT_SYSADDR, and if there is no value (value == 0), reads from PREV_SYSADDR. TMPSTORE(key, value) stores to CURRENT_SYSADDR if value is nonzero, and if it is 0, deletes the slot from both accounts. The reason both are cleared is that reads fall back from current to previous. If only the current one were cleared, an old value from the previous period could reappear, so clearing both accounts is necessary to guarantee that TMPLOAD(key) after TMPSTORE(key, 0) returns 0 until a new value is written. The calling convention follows SSTORE and SLOAD.

Gas rules: cheaper than SSTORE, more expensive than TSTORE

The gas rules follow the SSTORE/SLOAD conventions of EIP-2929 and EIP-2200, with four exceptions. First, the cost must be much lower than SSTORE/SLOAD and higher than TSLOAD/TSTORE. Second, clearing temporary storage gives no refund. Third, TMPLOAD can perform up to two storage reads as it checks the current and previous accounts in turn, and gas MUST reflect this. Fourth, TMPSTORE's deletion updates the storage roots of both system accounts, so it is more expensive than creation or modification, and gas MUST reflect this. The specific figures TMPLOAD_GAS, COLD_TMPLOAD_COST, TMPSTORE_SET_GAS, and TMPSTORE_RESET_GAS are all still TBD.

Activation and reserved address handling

At FORK_BLOCK, the chain must treat the two system addresses as reserved addresses. If the corresponding account does not exist in the state trie, it is created with nonce = 1, balance = 0, codeHash = EMPTY_CODE_HASH, and storageRoot = EMPTY_TRIE_ROOT. No contract code is deployed at these addresses. Since the behavior of existing opcodes is unchanged, it is compatible with existing contract accounts, but introducing it requires a hard fork.

Design rationale: why two periods, why two accounts

EIP-1153's transient storage is discarded with every transaction, so it suits uses within a single transaction, whereas this EIP targets uses that persist across multiple transactions and blocks but do not need indefinite retention. The two-period rollover was chosen for a lifetime guarantee: an entry is kept for at least one period after being written and disappears after at most two periods. With a single global rollover, data written near the end of a period could be cleared almost immediately, which would be unfriendly to developers. Using two accounts enables constant-time rollover: at each period boundary, only the current account's storageRoot needs to change, the previous account is kept for one more period, and storage older than one period becomes unreachable and can be pruned.

Security considerations

Writes to temporary storage also create state that must be processed and stored for at least one period. Gas costs must therefore be set so that even in the worst case, no per-block disk I/O DoS vector arises beyond that of existing storage writes. Clients must retain enough history to handle reorgs of plausible depth. Contracts must treat temporary storage as space that can disappear at any time, and MUST handle the case where an entry is unexpectedly missing.

Current status: Draft, key values undetermined

This EIP is in Draft status, so its contents may still change. The activation block (FORK_BLOCK), the period length (TEMP_STORAGE_PERIOD), the two system addresses, and the four gas constants are all left as TBD. There is also no core developer call decision yet on which fork it will be included in.

Original EIP · ← EIPs