📖 This EIP is in the review stage. It is subject to changes and feedback is appreciated.

EIP-1153: Transient storage opcodes Source

Add opcodes for manipulating state that behaves identically to storage but is discarded after every transaction

AuthorAlexey Akhunov, Moody Salem
Discussions-Tohttps://ethereum-magicians.org/t/eip-transient-storage-opcodes/553
StatusReview
TypeStandards Track
CategoryCore
Created2018-06-15
Requires 2200, 3529

Abstract

This proposal introduces transient storage opcodes, which manipulate state that behaves identically to storage, except that transient storage is discarded after every transaction. In other words, the values of transient storage are never deserialized from storage or serialized to storage. Thus transient storage is cheaper since it never requires disk access. Transient storage is accessible to smart contracts via 2 new opcodes, TLOAD and TSTORE, where “T” stands for “transient:”

TLOAD  (0xb3)
TSTORE (0xb4)

Motivation

Running a transaction in Ethereum can generate multiple nested frames of execution, each created by CALL (or similar) instructions. Contracts can be re-entered during the same transaction, in which case there are more than one frame belonging to one contract. Currently, these frames can communicate in two ways: via inputs/outputs passed via CALL instructions, and via storage updates. If there is an intermediate frame belonging to another untrusted contract, communication via inputs/outputs is not secure. Notable example is a reentrancy lock which cannot rely on the intermediate frame to pass through the state of the lock. Communication via storage (SSTORE/SLOAD) is costly. Transient storage is a dedicated and gas efficient solution to the problem of inter frame communication.

Storage refunds accumulated due to inter frame communication are also limited to 20% of gas spent by a transaction due to EIP-3529 (introduced in the London hard fork). This greatly reduces the refunds for transiently-set storage slots in otherwise low-cost transactions. For example, in order to receive the full refund of one re-entrancy lock, the transaction must spend ~80k gas on other operations.

Language support could be added in relatively easy way. For example, in Solidity, a qualifier transient can be introduced (similar to the existing qualifiers memory and storage, and Java’s own transient keyword with a similar meaning). Since the addressing scheme of TSTORE and TLOAD is the same as for SSTORE and SLOAD, code generation routines that exist for storage variables, can be easily generalised to also support transient storage.

Potential use cases enabled or improved by this EIP include:

  1. Reentrancy lock
  2. Constructor arguments loaded from the factory contract (for on-chain-computable CREATE2 addresses as in Uniswap V3)
  3. Single transaction ERC20 approvals, e.g. #approveAndCall(address callee, uint256 amount, bytes memory data)
  4. More generic libraries that use callbacks, for example generalised sorting with functions Less and Swap defined.
  5. Contracts that require control before and after method execution (e.g. via callbacks)
  6. Shared memory (borrowed from early draft of similar EIP by @holiman). When implementing contract-proxies using DELEGATECALL, all direct arguments are relayed from the caller to the callee via the CALLDATA, leaving no room for meta-data between the proxy and the proxee. Also, the proxy must be careful about storage access to avoid collision with target storage-slots. Since transient storage would be shared, it would be possible to use transient storage to pass information between the proxy and the target.

These opcodes are more efficient to execute than the SSTORE and SLOAD opcodes because the original value never needs to be loaded from storage (i.e. is always 0). The gas accounting rules are also simpler, since no refunds are required.

Specification

Two new opcodes are added to EVM, TLOAD (0xb3) and TSTORE (0xb4). Note that previous drafts of this EIP specified the values 0x5c and 0x5d for TLOAD and TSTORE respectively, but these have been modified so as not to conflict with other draft EIPs.

They use the same arguments on stack as SLOAD (0x54) and SSTORE (0x55).

TLOAD pops one 32-byte word from the top of the stack, treats this value as the address, fetches 32-byte word from the transient storage at that address, and pops the value on top of the stack.

TSTORE pops two 32-byte words from the top of the stack. The word on the top is the address, and the next is the value. TSTORE saves the value at the given address in the transient storage.

Addressing is the same as SLOAD and SSTORE. i.e. each 32-byte address points to a unique 32-byte word.

Gas cost for TSTORE is the same as a warm SSTORE of a dirty slot (i.e. original value is not new value and is not current value, currently 100 gas), and gas cost of TLOAD is the same as a hot SLOAD (value has been read before, currently 100 gas). Gas cost cannot be on par with memory access due to transient storage’s interactions with reverts.

All values in transient storage are discarded at the end of the transaction.

Transient storage is private to the contract that owns it, in the same way as persistent storage. Only owning contract frames may access their transient storage. And when they do, all the frames access the same transient store, in the same way as persistent storage, but unlike memory.

When transient storage is used in the context of DELEGATECALL or CALLCODE, then the owning contract of the transient storage is the contract that issued DELEGATECALL or CALLCODE instruction (the caller) as with persistent storage. When transient storage is used in the context of CALL or STATICCALL, then the owning contract of the transient storage is the contract that is the target of the CALL or STATICCALL instruction (the callee).

If a frame reverts, all writes to transient storage that took place between entry to the frame and the return are reverted, including those that took place in inner calls. This mimics the behavior of persistent storage.

If the TSTORE opcode is called within the context of a STATICCALL, the call must revert. TLOAD is allowed within the context of a STATICCALL.

Rationale

Another option to solve the problem of inter-frame communication is repricing the SSTORE and SLOAD opcodes to be cheaper for the transient storage use case. This has already been done as of EIP-2200. However, EIP-3529 reduced the maximum refund to only 20% of the transaction gas cost, which means the use of transient storage is severely limited.

Another approach is to keep the refund counter for transient storage separate from the refund counter for other storage uses, and remove the refund cap for transient storage. However, that approach is more complex to implement and understand. For example, the 20% refund cap must be applied to the gas used after subtracting the uncapped gas refund. Otherwise, the refund amount available subject to the 20% refund cap could be increased by executing transient storage writes. Thus it is preferable to have a separate mechanism that does not interact with the refund counter. Future hard forks can remove the complex refund behavior meant to support the transient storage use case, encouraging migration to contracts that are more efficient for the Ethereum clients to execute.

Relative cons of this transient storage EIP:

  • Does not address transient usages of storage in existing contracts
  • New code in the clients
  • New concept for the yellow paper (more to update)

Relative pros of this transient storage EIP:

  • Transient storage opcodes are considered separately in protocol upgrades and not inadvertently broken (e.g. EIP-3529)
  • Clients do not need to load the original value
  • No upfront gas cost to account for non-transient writes
  • Does not change the semantics of the existing operations
  • No need to clear storage slots after usage
  • Simpler gas accounting rules
  • Future storage designs (e.g. Verkle tree) do not need to account for transient storage refunds

Backwards Compatibility

This EIP requires a hard fork to implement.

Since this EIP does not change behavior of any existing opcodes, it is backwards compatible with all existing smart contracts.

Reference Implementation

Because the transient storage must behave identically to storage within the context of a single transaction with regards to revert behavior, it is necessary to be able to revert to a previous state of transient storage within a transaction. At the same time reverts are exceptional cases and loads, stores and returns should be cheap.

A map of current state plus a journal of all changes and a list of checkpoints is recommended. This has the following time complexities:

  • On entry to a call frame, a call marker is added to the list - O(1)
  • New values are written to the current state, and the previous value is written to the journal - O(1)
  • When a call exits successfully, the marker to the journal index of when that call was entered is discarded - O(1)
  • On revert all entries are reverted up to the last checkpoint, in reverse - O(N) where N = number of journal entries since last checkpoint
interface JournalEntry {
    addr: string
    key: string
    prevValue: string
}

type Journal = JournalEntry[]

type Checkpoints = Journal['length'][]

interface Current {
    [addr: string]: {
        [key: string]: string
    }
}

const EMPTY_VALUE = '0x0000000000000000000000000000000000000000000000000000000000000000'

class TransientStorage {
    /**
     * The current state of transient storage.
     */
    private current: Current = {}
    /**
     * All changes are written to the journal. On revert, we apply the changes in reverse to the last checkpoint.
     */
    private journal: Journal = []
    /**
     * The length of the journal at the time of each checkpoint
     */
    private checkpoints: Checkpoints = [0]

    /**
     * Returns the current value of the given contract address and key
     * @param addr The address of the contract
     * @param key The key of transient storage for the address
     */
    public get(addr: string, key: string): string {
        return this.current[addr]?.[key] ?? EMPTY_VALUE
    }

    /**
     * Set the current value in the map
     * @param addr the address of the contract for which the key is being set
     * @param key the slot to set for the address
     * @param value the new value of the slot to set
     */
    public put(addr: string, key: string, value: string) {
        this.journal.push({
            addr,
            key,
            prevValue: this.get(addr, key),
        })

        this.current[addr] = this.current[addr] ?? {}
        this.current[addr][key] = value;
    }

    /**
     * Commit all the changes since the last checkpoint
     */
    public commit(): void {
        if (this.checkpoints.length === 0) throw new Error('Nothing to commit')
        this.checkpoints.pop() // The last checkpoint is discarded.
    }

    /**
     * To be called whenever entering a new context. If revert is called after checkpoint, all changes made after the latest checkpoint are reverted.
     */
    public checkpoint(): void {
        this.checkpoints.push(this.journal.length)
    }

    /**
     * Revert transient storage to the state from the last call to checkpoint
     */
    public revert() {
        const lastCheckpoint = this.checkpoints.pop()
        if (typeof lastCheckpoint === 'undefined') throw new Error('Nothing to revert')

        for (let i = this.journal.length - 1; i >= lastCheckpoint; i--) {
            const {addr, key, prevValue} = this.journal[i]
            // we can assume it exists, since it was written in the journal
            this.current[addr][key] = prevValue
        }
        this.journal.splice(lastCheckpoint, this.journal.length - lastCheckpoint)
    }
}

The worst case time complexity can be produced by writing the maximum number of keys that can fit in one block, and then reverting. In this case, the client is required to do twice as many writes to apply all the entries in the journal. However, the same case applies to the state journaling implementation of existing clients, and cannot be DOS’d with the following code.

pragma solidity =0.8.13;

contract TryDOS {
    uint256 slot;

    constructor() {
        slot = 1;
    }

    function tryDOS() external {
        uint256 i = 1;
        while (gasleft() > 5000) {
            unchecked {
                slot = i++;
            }
        }
        revert();
    }
}

Security Considerations

TSTORE presents a new way to allocate memory on a node with linear cost. In other words, each TSTORE allows the developer to store 32 bytes for 100 gas, excluding any other required operations to prepare the stack. Given 30 million gas, the maximum amount of memory that can be allocated using TSTORE is:

30M gas * 1 TSTORE / 100 gas * 32 bytes / 1 TSTORE * 1MB / 2^20 bytes ~= 9.15MB

Given the same amount of gas, the maximum amount of memory that can be allocated in a single context by MSTORE is ~3.75MB:

30M gas = 3x + x^2 / 512 => x = ~123,169 32-byte words
~123,169 words * 32 bytes/word * 1MB / 2^20 bytes = 3.75MB

However, if you only spend 1M gas allocating memory in each context, and make calls to reset the memory expansion cost, you can allocate ~700KB per million gas, for a total of ~20MB of memory allocated:

1M gas = 3x + x^2 / 512 => x = ~21,872 32-byte words
30M gas * ~21,872 words / 1M gas * 32 bytes/word * 1MB / 2^20 bytes = ~20MB

For smart contract developers, there are no security considerations for existing contracts because they do not contain the new TSTORE or TLOAD opcodes. New contracts that do use the TSTORE and TLOAD opcodes operate under all the same assumptions as with storage. This EIP introduces no additional mental overhead for the developer. In some cases, transient storage simplifies contracts in that contract transient storage does not need to be cleared at the end of every transaction, e.g. in the ERC20 temporary approvals use case.

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Alexey Akhunov, Moody Salem, "EIP-1153: Transient storage opcodes," Ethereum Improvement Proposals, no. 1153, June 2018. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-1153.