Experimental: StorageKey feature

[mohammadfawaz]

Description

This PR introduces StorageHandle to the core as an experimental feature. StorageHandle is a descriptor of a location in storage containing two fields:

1. A key pointing to a storage slot s.
2. An offset pointing to a particular word in s or in its subsequent slots. This offset is new and is not described in the RFC. I will rectify that shortly.
   The standard library introduces helper methods read, try_read, and write to StorageHandle that allow reading from and writing to the location pointed to by the handle. try_read returns an Option wrapping the data while read automatically internally unwraps the data and could panic.

The summary of this change is as follows:

• New struct core::experimental::storage::StorageHandle
• New storage library std::experimental::storage::* that should eventually replace std::storage::*. This new library mirrors the old one to the extent possible and introduces the helper methods for StorageHandle. Other data structures such as StorageVec and StorageBytes will be introduced in a separate PR.
• Add an experimental flag --experimental-storage to forc that enables all the required code in the compiler to support StorageHandle as described in the Introducing StorageKey sway-rfcs#23.
  • Type checking phases assumes the existence of StorageHandle and monomorphizes it as needed.
  • Storage accesses now always return StorageHandle and storage reassignment are no longer relevant.
  • IR gen handles storage accesses by "filling" the key and the offset in an aggregate representing the StorageHandle. The key and the offset are statically determined based on the index of the storage variable in the storage block and the field accessed, if applicable.
  • Storage initializers are now handled based on the new model
  • The new approach packs struct fields by default but does not pack across storage variables. This offers the most amount of flexibility. This is a deviation from the RFC which I will update shortly.
  • To implement StorageMap and other dynamic storage data structures, we now write impl StorageHandle<StorageMap<K, V>> instead of impl StorageMap<K, V> directly. Also, note that the get method now returns a StorageHandle instead of the actual data. To get the actual data, read() or try_read() should be called on the resulting handle. This is needed for multiple reasons including proper support for nested dynamic storage types. Rust also does the same, in a way (where get actually returns & which happens to coerce to the real data in certain places).
• I added various tests but they're not comprehensive. Some tests on my list:
  • Extensive tests for storage maps in structs (which now work!)
  • Extensive tests for storage accesses with various types and struct layouts

I still need to figure out how to do nested dynamic storage types with this approach. The stuff I have in map_in_map_access in test_projects/experimental_storage/src/main.sw is just an attempt but not ergonomic at all of course.

Checklist

• I have linked to any relevant issues.
• I have commented my code, particularly in hard-to-understand areas.
• I have updated the documentation where relevant (API docs, the reference, and the Sway book).
• I have added tests that prove my fix is effective or that my feature works.
• I have added (or requested a maintainer to add) the necessary Breaking* or New Feature labels where relevant.
• I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
• I have requested a review from the relevant team or maintainers.

[mohammadfawaz]

Ah conflicts.. let me fix.

[nfurfaro]

looks great! I just left a couple comments/questions.

[mitchmindtree]

Looking good to me! Left some minor suggestions, but will leave it up to you if you think they're worth addressing.