ERC-8119 Parameterized storage key format (Parameterized Storage Keys)
Draft · Other · created 2025-01-06
Defines a common string format for attaching parameters to keys, such as registration/1 or user[alice], in smart contract key-value storage. It unifies key notations that previously varied by implementation.
Why it is needed
Ethereum smart contracts often use key-value storage, pairing string keys with values to store metadata. However, when there are multiple instances of the same kind of metadata, for example storing registration records 1, 2, and 3 separately, a parameter such as a number must be attached to the key name. Until now, there has been no standard way to attach such parameters, so each implementation did it differently. If one project uses a hyphen and another uses a different delimiter, interoperability breaks when one app tries to read keys stored by another, since the interpretation rules differ, and mechanically parsing the keys also becomes difficult. This standard defines a common format for parameterized string keys to reduce this confusion.
In depth
Two encodings
A key with a parameter must use exactly one of two formats. The first is the slash/colon format, <key-label>/<key-parameter> or <key-label>:<key-parameter>, with exactly one parameter. The second is the bracket format, <key-label>[<key-parameter-1>][<key-parameter-2>]..., which can attach one or more parameters. Mixing the two formats in a single key is not allowed. For example, key/param[extra] is an invalid format.
key-label character rules
A key-label may use only printable ASCII characters, excluding space, slash (/), colon (:), and left bracket ([). The allowed code points are 0x21-0x2E, 0x30-0x39, 0x3B-0x5A, 0x5C-0x7E, while control characters (0x00-0x1F), space (0x20), slash (0x2F), colon (0x3A), left bracket (0x5B), and DEL (0x7F) are explicitly excluded. Excluding these four characters from the label lets both encodings be parsed without ambiguity. Special characters such as percent, dollar, and hash can be used in labels, as in %gain/50, $price/100, and #tag/featured.
Parsing rules for the slash/colon format
Parsing takes whichever of / or : appears first in the string as the delimiter, and treats every character after it as a single parameter. This means a parameter can contain additional / or : characters without issue, as in website/http://website.com or key/value/with/slashes. Since the parameter only needs to be a UTF-8 string, keys such as name/María, description/说明, or title/タイトル are also valid. However, the character immediately after the delimiter must not be a space. key/ value is an invalid format, while a space in the middle, as in key/hello world, is allowed. If data that must start with a space is needed, use quoted encoding, placing a space as the first character inside quotes.
Parsing rules for the bracket format
The parser reads everything up to immediately before the first [ as the label, then reads one or more bracket-enclosed parameters in order. Each parameter can be any UTF-8 string except the reserved closing delimiter ], so UTF-8 parameters are also possible, as in title[说明][日本語]. No character may follow the last ]. Therefore an unclosed bracket, as in key[label, or trailing characters after the bracket, as in key[]tail, are invalid formats. The bracket format was added to express multiple parameters as an explicit structure, without encoding them all into a single string.
Why these delimiters were chosen
Slash and colon are clear delimiters that are easy to parse programmatically, and the rule of using whichever appears first keeps the parsing rule singular while still allowing both characters to reappear inside a parameter. They are also short and readable, suiting long text values, and require no closing ] at the end. Excluding /, :, and [ from the label is not a major constraint, since labels are mainly ASCII to begin with, and prohibiting a space immediately after the delimiter keeps parsing simple and avoids ambiguity.
Scope of application and backward compatibility
This format applies to any EVM-compatible language that supports string-keyed storage, such as Solidity's mapping(string => bytes) or Vyper's hash maps. The reference implementation shows a Solidity contract that stores and reads back values using the registration/1, registration/2, and registration/3 keys. This ERC is fully backwards compatible. Existing implementations that do not write parameter keys are unaffected, and implementations using non-standard formats continue to work, though migrating to this format is recommended for interoperability.
A Proposal in Draft Stage
This ERC is in Draft status, created on January 6, 2025. Format rules may change or the proposal may stall during discussion, so it is advisable to check the latest source text before implementing.
Things to watch out for
- Validating keys built from user input: When building a key from user input, clients must check that the key-label falls within the allowed ASCII range and must reject labels containing spaces, /, :, or [. In the slash/colon format, keys with a space immediately after the delimiter must also be rejected to prevent ambiguous or non-standard keys.
- Rejecting malformed input in the bracket format: Clients that support the bracket format must reject malformed input such as unmatched brackets, characters remaining after the final ], or mixing of slashes and brackets. This prevents parsers from diverging in how they interpret such input.