Storage domains

[ironcev]

This is a tracking issue for Storage domains.
The experimental feature flag for the issue is storage_domains.

Description

Certain storage types, like, e.g., StorageMap allow storage slots of their contained elements to be defined based on developer's input. E.g., the key in a StorageMap used to calculate the storage slot is a developer input.

To ensure that pre-images of such storage slots can never be the same as a pre-image of compiler generated key of a storage field, we will prefix the pre-images of storage fields with a single byte that denotes the storage field domain. Storage types like StorageMap must have a different domain prefix than this STORAGE_DOMAIN which will be set to 0u8.

For detailed elaboration see #6317.

Breaking Changes

Storage domains changes how storage keys are generated for storage fields. The previous formula for calculating storage fields' keys was:

sha256("storage::<optional namespace 1>::<optional namespace 2>.<field name>")

The new formula prefixes the field path with 0u8:

sha256((0u8, "storage::<optional namespace 1>::<optional namespace 2>.<field name>"))

To calculate old and new slot keys for storage field paths, you can run this Rust code.

Review explicitly defined slot keys in storage declarations (in keywords)

If you've used the in keyword in storage declarations to manually assign slot keys, and if the assigned keys were representing the keys of storage fields of contracts that will be newly compiled, you might want to recalculate the storage keys.

For illustration, in this example, we have three storage fields and three fields declared using the in keyword that hard-code the slot keys of the other three fields. The example shows the old and the new keys, calculated with the old and the new formula, respectively.

storage {
    // Old slot key: c979570128d5f52725e9a343a7f4992d8ed386d7c8cfd25f1c646c51c2ac6b4b
    // New slot key: 419b1120ea993203d7e223dfbe76184322453d6f8de946e827a8669102ab395b
    x: u64 = 0,
    namespace_1 {
        // Old slot key: 2f055029200cd7fa6751421635c722fcda6ed2261de0f1e0d19d7f257e760589
        // New slot key: 50a62a537821cd5e77fd4093bb0febc39a0253b2bf65ffcdffb7297d9556afac
        y: u64 = 0,
        namespace_2 {
            // Old slot key: 03d2ee7fb8f3f5e1084e86b02d9d742ede96559e44875c6210c7008e2d184694
            // New slot key: e6967a9e92c754da39a64baaaec3d8a56194ac400f5dd66cc2b509a77ea98a64
            z: u64 = 0,
        }
    }

    // Review if these keys should be replaced with the new keys.
    same_as_x in 0xc979570128d5f52725e9a343a7f4992d8ed386d7c8cfd25f1c646c51c2ac6b4b: u64 = 0,
    same_as_y in 0x2f055029200cd7fa6751421635c722fcda6ed2261de0f1e0d19d7f257e760589: u64 = 0,
    same_as_z in 0x03d2ee7fb8f3f5e1084e86b02d9d742ede96559e44875c6210c7008e2d184694: u64 = 0,
}

Explicitly define storage slot keys if they need to be backward compatible

If the contract owning the storage is behind a proxy, its storage field keys must be backward compatible and the same as the old keys. In this, and any other case where the backward compatibility of the storage slot keys is needed, the old keys must be explicitly defined for storage fields, by using the in keyword and the old keys.

E.g., assume we have a contract with the following storage behind a proxy:

storage {
    x: u64 = 0,
    namespace_1 {
        y: u64 = 0,
        namespace_2 {
            z: u64 = 0,
        }
    }
}

To keep the fields' storage slots backward compatible, we must give them slot keys calculated using the old formula:

storage {
    x in 0xc979570128d5f52725e9a343a7f4992d8ed386d7c8cfd25f1c646c51c2ac6b4b: u64 = 0,
    namespace_1 {
        y in 0x2f055029200cd7fa6751421635c722fcda6ed2261de0f1e0d19d7f257e760589: u64 = 0,
        namespace_2 {
            z in 0x03d2ee7fb8f3f5e1084e86b02d9d742ede96559e44875c6210c7008e2d184694: u64 = 0,
        }
    }
}

Steps

• Compiler/std-lib: storage collison between variables and StorageMap, allows hidden backdoors, likely loss of funds #6317