diff --git a/docs/developers/meta/rust-nightly.md b/docs/developers/meta/rust-nightly.md new file mode 100644 index 000000000..b07e718a8 --- /dev/null +++ b/docs/developers/meta/rust-nightly.md @@ -0,0 +1,190 @@ +--- +id: rust-nightly +title: Nightly Rust +--- + +[comment]: # (mx-abstract) + +## Why Nighly? + +The Rust framework currently requires nightly Rust to run. This often causes issues with the inherent instability and frequent changes in the Rust compiler. + +While it would be ideal to have our infrastructure running on stable Rust, there are a number of features that we currently require. + +This page is intended to provide a list of all these features that we use, and explain what it would take to renounce them and move to stable. + + +[comment]: # (mx-context-auto) + +## Nightly features + + + +export const NightlyFeaturesTable = () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureWhy we need itWhat it would take to discard
+ never_type and exhaustive_patterns + +

+ The codec is optimized to work within smart contracts, but also to be used outside them, in a standard environment. Encoding and decoding functions return Result, because we want to allow programs to recover from a failed encoding or decoding attempt. However, this feature is not needed in contracts, where we want failures to interrupt execution immediately. +

+

+ Our solution relies heavily on the never type (!), to guide the compiler to discard any error recovery when compiling contracts. +

+

+ Exhaustive patterns are a nice way to engage with code that is guaranteed at compile time to never return an error. +

+
+

+ The never_type seems to be close to being stabilized. +

+

+ Exhaustive patterns, if not stabilized soon, could be replaced with regular patterns with an unreacheable clause on the else. +

+
+ auto_traits and negative_impls + +

+ We have a feature that allows safe conversions from one type to another via the codec. For instance, a smaller integer can be safely cast to a larger one. This feature is central to proxies and transaction syntax. +

+

+ We are using auto-traits and negative implementations to overcome overlaps in the implementations of the CodecFrom trait. +

+
+

+ Could be replaced by relying more heavily on proc-macros. We would need a way to generate the CodecFrom<Self> when deriving TopEncode and TopDecode. +

+

+ Alternately, we could wait for an overlapping marker trait impls. +

+
+ try_trait_v2 + +

+ Used in the deprecated SCResult type. +

+
+

+ Remove SCResult. +

+
+ maybe_uninit_uninit_array and maybe_uninit_array_assume_init + +

+ Used in ManagedVec to_array_of_refs. +

+
+

+ There are less elegant ways to write that method, without using these features. +

+
+ generic_const_exprs + +

+ Used everywhere in working with the ManagedVec payload, without using the heap. They allow us to allocate variable sized byte arrays on the stack. +

+
+

+ Using universal fixed-sized arrays on heap for handling payloads. Might hurt performance, and might also occasionally run into overflows. +

+
+ slice_partition_dedup + +

+ Used in ManagedVec dedup. +

+
+

+ We could probably replace that one with an in-house de-duplication function. +

+
+ is_sorted + +

+ Used in ManagedVec is_sorted, is_sorted_by, and is_sorted_by_key. These methods are currently mostly used in tests. +

+
+

+ We could probably replace them with in-house equivalent functions. +

+
+ panic_info_message + +

+ Used in the wasm adapter to retrieve panic messages, for debugging purposes. +

+
+

+ Figuring out a way to use the format function provided by the stable version of the library, without performing memory allocation. +

+
+); + +[comment]: # (mx-context-auto) + +## Deal breakers + +Some of the nightly features that we use could be easily replaced with something from stable. However, there are a few essential ones that we have yet no solution for: + +[comment]: # (mx-context-auto) + +### `generic_const_exprs` + +This one is very difficult to get rid of without compromising the `ManagedVec` functionality. We have also recently added a new `ManagedDecimal` component that makes use of this feature. This is the main deal breaker right now for switching to stable Rust. + +[comment]: # (mx-context-auto) + +### `never_type` + +Our entire codec relies on the never type. There might be a workaround using void enums, not sure if it works. Fortunately, this feature is close to being stabilized. + +[comment]: # (mx-context-auto) + +### `auto_traits` and `negative_impls` + +This is not impossible to overcome, but would need a redesign of some of the codec traits. diff --git a/sidebars.js b/sidebars.js index 14643a1c0..170d08005 100644 --- a/sidebars.js +++ b/sidebars.js @@ -110,6 +110,7 @@ const sidebars = { "developers/meta/sc-config", "developers/meta/sc-meta-cli", "developers/meta/sc-allocator", + "developers/meta/rust-nightly", ], }, {