ERC-6823 Token mapping slot lookup extension (Token Mapping Slot Retrieval Extension)

Draft · Tokens · created 2023-03-29

Adds a function to ERC-20/721/1155 token contracts that reveals the storage slot where the ownership mapping is stored, so external tools can verify transaction outcomes directly from storage rather than relying on events.

Why it is needed

In smart contracts, a mapping has no fixed size, so each value is scattered into a separate storage location computed with a keccak-256 hash. This location depends on which variable number the mapping was declared as within the contract, and since the order of variable declarations differs from contract to contract, it cannot be determined externally by any universal method. As a result, even when an external tool pre-executes a transaction such as a token transfer (an off-chain simulation), it cannot be certain exactly where the ownership data is actually recorded. Simulation then ends up relying heavily on the events the contract emits, but the original text points out that events are only reference information and the sole source of truth should be state (storage). Because the storage layout is unknown, there arises the problem that storage, which is actually the source of truth, cannot be directly verified, forcing reliance on information emitted by the application layer instead.

What to implement

In depth

How mappings are stored and the root of the problem

EVM storage is a key-value store with 32-byte keys and 32-byte values. State variables are assigned positions 0, 1, 2, and so on in declaration order, and multiple values smaller than 32 bytes are packed into a single slot where possible. A mapping, since its size is unknown, only occupies a placeholder slot, and the location of the value for key k is determined by concatenating h(k) with the mapping's position p and hashing the result with keccak-256. Since p depends on the order and nature of the variables declared before the mapping, it can only be obtained by knowing the implementation. This structure applies not only to Solidity but commonly to other languages such as Vyper as well.

Requirements for the getTokenLocationRoot function

Implementers MUST implement the getTokenLocationRoot() function, and this function MUST return the storage slot reserved for the mapping type in the contract. The declaration SHOULD be external pure. The reference implementation is a one-line function that reads <mapping_name>.slot in assembly and returns it as bytes32, and the ERC-20, ERC-721, and ERC-1155 extensions all take the same form.

A single universal entry point

The function name was deliberately made generic so that the three token standards could share the same implementation. Once this function is universally implemented, a single selector derived from the function signature becomes one entry point that directly reads the ownership storage slot of any token contract. The source material explains that this makes off-chain simulation far more accurate and leaves events to serve purely informational purposes.

Example of verification use

The caller computes the storage location for a specific token ID from the returned slot, then compares that value against an expected value to verify the action announced by an event. For an ERC-721 mint, the slot value is compared against the token owner's address; for an ERC-20 transfer, against the new owner's address; for an ERC-1155 burn, against the zero address. The comparison can be performed with existing tooling. The source material adds that this could also enable atomic storage proofs that track ownership of a specific token by proving only a single location rather than the entire state.

Cost and compatibility

The design aims for a concise approach that does not break compatibility with existing standards. Adding a single function increases contract deployment cost only marginally, while calling this function externally costs nothing at all. The implementation is kept minimal so it is directly compatible with the major languages used for EVM smart contract development today. No backward compatibility issues have been found.

Proposal status

This proposal has been in Draft status since March 2023. Since the content may still change, it is advisable to check the latest status before implementing it.

Original ERC · ← ERCs