Attribute for checking of trivial encoding and decoding

docs/book/spell-check-custom-words.txt

@@ -275,3 +275,9 @@ Preload
 preloads
 Preloads
 VM's
+Decodable
+Encodable
+callee
+decodable
+encodable
+Vec

docs/book/src/SUMMARY.md

@@ -51,6 +51,7 @@
   - [Generics and Trait Constraints](./advanced/generics_and_trait_constraints.md)
   - [Assembly](./advanced/assembly.md)
   - [Never Type](./advanced/never_type.md)
+  - [Trivial Encoding](./advanced/trivial_encoding.md)
 - [Common Collections](./common-collections/index.md)
   - [Vectors on the Heap](./common-collections/vec.md)
   - [Storage Vectors](./common-collections/storage_vec.md)

docs/book/src/advanced/trivial_encoding.md

@@ -0,0 +1,96 @@
+# Trivially Encodable & Decodable Types
+
+When a contract calls another contract, all arguments are **encoded** just before the call is actually executed,
+and the callee **decodes** these arguments right before the target method starts.
+This adds a small but non‑negligible gas cost, from hundreds to thousands of gas depending on the complexity of the arguments.
+
+The Sway compiler mitigates this overhead for a subset of types that can be **trivially encoded** and/or **trivially decoded** –
+that is, types that their *runtime representation*, how the type bytes are laid out inside the VM, is *identical* to their *encoded representation*,
+how their bytes are laid out in the encoded buffer.
+
+For such types the compiler can skip the encoding/decoding process entirely, saving gas and simplifying the generated code.
+
+> **Trivial encoding** – encoding is replaced with a simple "transmute".
+> **Trivial decoding** – encoding is replaced with a simple "transmute".
+
+The compiler can skip each individually, but the whole gain comes only when both are skipped together.
+
+## Checking Triviality
+
+Each struct that should be treated as trivially encodable/decodable can be annotated with the `#[trivial]` attribute:
+
+```sway
+#[trivial(encode = "require", decode = "require")]
+pub struct SomeArgument {
+    a: bool,
+    b: SomeEnum,
+}
+```
+
+- `encode = "require"` – the compiler will check if the type is trivially encodable; if not, the build fails.
+- `decode = "require"` – similarly for decoding.
+
+Possible values are:
+
+- required: compiler will check and error if the check fails;
+- optional: compiler will only warn non-compliance;
+- any: nothing will be checked.
+
+This attributed can be used directly on types, but also on entry points such as "main" function for scripts and predicates; and contract methods for contracts.
+
+## Which Types Are Trivial?
+
+| Type | Trivially Encodable | Trivially Decodable | Notes |
+|------|---------------------|---------------------|-------|
+| `bool` | ✅ | ❌ | `bool` encodes to a single byte (`0` or `1`), but decoding must validate that the byte is a legal value. |
+| `u8`, `u64`, `u256`, `b256` | ✅ | ✅ |  |
+| `u16`, `u32` | ❌ | ❌ | Their runtime representation is actually a `u64` |
+| Structs | ✅ If all their members are trivial | ✅ If all their member are trivial | Recursively evaluated. |
+| Enums | ✅ If all variants are trivial | ❌ | Enums have an `u64` discriminant that cannot be trivially decodable. |
+| Arrays | ✅ If the item type is trivial | ✅ if the item type is trivial |
+| String Arrays | ✅ See * | ✅ See * |  |
+| Vec, Dictionary, String, etc. | ❌ | ❌ | Data Structures are never trivial |
+
+Only when the feature "str_array_no_padding" is turned on. When the feature toggle is off, only string arrays that its length is multiple of 8.
+
+### Why `bool` and `enum` are not trivially decodable
+
+Probably the most surprising non trivial base data type is `bool`. Mainly because `bool` is obviously trivially encodable. But there is no guarantee
+that buffer does not have a value like `2`, that being "transmuted" into a bool would be allow its runtime representation to be `2`, which is **undefined behaviour**.
+
+The same limitation applies to enums. Enums are implemented as "tagged unions" which means that their runtime representation has a discriminant value as `u64`. There
+is no guarantee that the buffer  would have a valid value for its discriminant.
+
+---
+
+## 3. Workaround for Non‑trivial Types
+
+If you need to expose a `bool` or an enum as a public argument, you can either:
+
+1. **Manual validation** – expose a raw `u64` (or `u8`) and check its value in the callee.
+
+```sway
+#[trivial(encode = "require", decode = "require")]
+pub struct Flag(u8);  // manually validate that value <= 1
+```
+
+1. **Custom wrappers** – Sway ships with `TrivialBool` and `TrivialEnum<T>` that enforce the bounds at compile time.
+
+   ```sway
+   use sway::primitive::TrivialBool;
+   use sway::primitive::TrivialEnum;
+
+   #[trivial(encode = "require", decode = "require")]
+   pub struct SomeArgument {
+       a: TrivialBool,
+       b: TrivialEnum<SomeEnum>,
+   }
+   ```
+
+   These wrappers automatically provide the guard checks and still let the compiler treat them as trivial.
+   Their usage is very similar to `Option<bool>`.
+
+   ```sway
+   let a: bool = some_argument.a.unwrap();
+   let b: SomeEnum = some_argument.b.unwrap();
+   ```

sway-ast/src/attribute.rs

@@ -65,6 +65,11 @@ pub const ABI_NAME_NAME_ARG_NAME: &str = "name";
 pub const EVENT_ATTRIBUTE_NAME: &str = "event";
 pub const INDEXED_ATTRIBUTE_NAME: &str = "indexed";
 
+// Require Attributes
+pub const REQUIRE_ATTRIBUTE_NAME: &str = "require";
+pub const REQUIRE_ARG_NAME_TRIVIALLY_ENCODABLE: &str = "trivially_encodable";
+pub const REQUIRE_ARG_NAME_TRIVIALLY_DECODABLE: &str = "trivially_decodable";
+
 pub const KNOWN_ATTRIBUTE_NAMES: &[&str] = &[
     STORAGE_ATTRIBUTE_NAME,
     DOC_COMMENT_ATTRIBUTE_NAME,
@@ -78,6 +83,7 @@ pub const KNOWN_ATTRIBUTE_NAMES: &[&str] = &[
     ABI_NAME_ATTRIBUTE_NAME,
     EVENT_ATTRIBUTE_NAME,
     INDEXED_ATTRIBUTE_NAME,
+    REQUIRE_ATTRIBUTE_NAME,
 ];
 
 /// An attribute declaration. Attribute declaration

sway-core/src/ir_generation.rs

@@ -11,7 +11,6 @@ use std::{
     collections::HashMap,
     hash::{DefaultHasher, Hasher},
 };
-
 use sway_error::error::CompileError;
 use sway_features::ExperimentalFeatures;
 use sway_ir::{
@@ -359,12 +358,16 @@ pub fn compile_program<'a>(
         .collect();
 
     let mut ctx = Context::new(engines.se(), experimental, backtrace);
-    ctx.program_kind = match kind {
+    let k = match kind {
         ty::TyProgramKind::Script { .. } => Kind::Script,
         ty::TyProgramKind::Predicate { .. } => Kind::Predicate,
         ty::TyProgramKind::Contract { .. } => Kind::Contract,
         ty::TyProgramKind::Library { .. } => Kind::Library,
     };
+    ctx.program_kind = k;
+
+    let module = Module::new(&mut ctx, k);
+    let mut md_mgr = MetadataManager::default();
 
     let mut compiled_fn_cache = CompiledFunctionCache::default();
     let mut panicking_fn_cache = PanickingFunctionCache::default();
@@ -384,6 +387,8 @@ pub fn compile_program<'a>(
             &mut panicking_fn_cache,
             &test_fns,
             &mut compiled_fn_cache,
+            &mut md_mgr,
+            module,
         ),
         ty::TyProgramKind::Predicate { entry_function, .. } => compile::compile_predicate(
             engines,
@@ -397,6 +402,8 @@ pub fn compile_program<'a>(
             &mut panicking_fn_cache,
             &test_fns,
             &mut compiled_fn_cache,
+            &mut md_mgr,
+            module,
         ),
         ty::TyProgramKind::Contract {
             entry_function,
@@ -415,6 +422,8 @@ pub fn compile_program<'a>(
             &test_fns,
             engines,
             &mut compiled_fn_cache,
+            &mut md_mgr,
+            module,
         ),
         ty::TyProgramKind::Library { .. } => compile::compile_library(
             engines,
@@ -427,6 +436,8 @@ pub fn compile_program<'a>(
             &mut panicking_fn_cache,
             &test_fns,
             &mut compiled_fn_cache,
+            &mut md_mgr,
+            module,
         ),
     }?;