updating documentation for u256 (#5111)

## Description This PR is part of #4794 and updates documentation for `u256` and improves test for edge cases. Code also prints more info when tests run in `verbose` mode. ## Checklist - [x] I have linked to any relevant issues. - [x] I have commented my code, particularly in hard-to-understand areas. - [x] I have updated the documentation where relevant (API docs, the reference, and the Sway book). - [x] I have added tests that prove my fix is effective or that my feature works. - [x] I have added (or requested a maintainer to add) the necessary `Breaking*` or `New Feature` labels where relevant. - [x] I have done my best to ensure that my PR adheres to [the Fuel Labs Code Review Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md). - [x] I have requested a review from the relevant team or maintainers. --------- Co-authored-by: IGI-111 <[email protected]>
FuelLabs · Sep 21, 2023 · ce0627e · ce0627e
1 parent b16c114
commit ce0627e
Show file tree

Hide file tree

Showing 21 changed files with 176 additions and 49 deletions.
diff --git a/docs/book/src/basics/built_in_types.md b/docs/book/src/basics/built_in_types.md
@@ -17,6 +17,7 @@ Sway has the following primitive types:
 1. `u16` (16-bit unsigned integer)
 1. `u32` (32-bit unsigned integer)
 1. `u64` (64-bit unsigned integer)
+1. `u256` (256-bit unsigned integer)
 1. `str[]` (fixed-length string)
 1. `str` (string slices)
 1. `bool` (Boolean `true` or `false`)
@@ -44,12 +45,14 @@ Numbers can be declared with binary syntax, hexadecimal syntax, base-10 syntax,
 <!-- default_num:example:start -->
 The default numeric type is `u64`. The FuelVM's word size is 64 bits, and the cases where using a smaller numeric type saves space are minimal.
 
-If a 64-bit arithmetic operation produces an overflow or an underflow,
+If a 64-bit or 256-bit arithmetic operation produces an overflow or an underflow,
 computation gets reverted automatically by FuelVM.
 
 8/16/32-bit arithmetic operations are emulated using their 64-bit analogues with
 additional overflow/underflow checks inserted, which generally results in
 somewhat higher gas consumption.
+
+The same does not happen with 256-bit operations, including `b256`, which uses specialized operations and are as performant as possible.
 <!-- default_num:example:end -->
 
 ## Boolean Type

diff --git a/docs/book/src/basics/comments_and_logging.md b/docs/book/src/basics/comments_and_logging.md
@@ -81,7 +81,7 @@ Note that `ra` will include the value being logged. The additional registers `rc
 
 <!-- This section should explain when `LogData` receipts are produced -->
 <!-- log_data_rec:example:start -->
-`LogData` is generated for _reference_ types which include all types except for _non_reference_ types.
+`LogData` is generated for _reference_ types which include all types except for _non_reference_ types; and for  _non-reference_ types bigger than 64-bit integers, for example, `u256`;
 <!-- log_data_rec:example:end -->
 
 For example, logging a `b256` variable `b` that holds the value `0x1111111111111111111111111111111111111111111111111111111111111111` using `log(b)` may generate the following receipt:

diff --git a/docs/book/src/reference/compiler_intrinsics.md b/docs/book/src/reference/compiler_intrinsics.md
@@ -80,7 +80,7 @@ __eq<T>(lhs: T, rhs: T) -> bool
 
 **Description:** Returns whether `lhs` and `rhs` are equal.
 
-**Constraints:** `T` is `bool`, `u8`, `u16`, `u32`, `u64`, or `raw_ptr`.
+**Constraints:** `T` is `bool`, `u8`, `u16`, `u32`, `u64`, `u256`, `b256` or `raw_ptr`.
 
 ___
 
@@ -90,7 +90,7 @@ __gt<T>(lhs: T, rhs: T) -> bool
 
 **Description:** Returns whether `lhs` is greater than `rhs`.
 
-**Constraints:** `T` is `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 ___
 
 ```sway
@@ -99,7 +99,7 @@ __lt<T>(lhs: T, rhs: T) -> bool
 
 **Description:** Returns whether `lhs` is less than `rhs`.
 
-**Constraints:** `T` is `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 ___
 
 ```sway
@@ -178,7 +178,7 @@ __add<T>(lhs: T, rhs: T) -> T
 
 **Description:** Adds `lhs` and `rhs` and returns the result.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 
 ___
 
@@ -188,7 +188,7 @@ __sub<T>(lhs: T, rhs: T) -> T
 
 **Description:** Subtracts `rhs` from `lhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 
 ___
 
@@ -198,7 +198,7 @@ __mul<T>(lhs: T, rhs: T) -> T
 
 **Description:** Multiplies `lhs` by `rhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 
 ___
 
@@ -208,7 +208,7 @@ __div<T>(lhs: T, rhs: T) -> T
 
 **Description:** Divides `lhs` by `rhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 
 ___
 
@@ -218,7 +218,7 @@ __and<T>(lhs: T, rhs: T) -> T
 
 **Description:** Bitwise AND `lhs` and `rhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 
 ___
 
@@ -228,7 +228,7 @@ __or<T>(lhs: T, rhs: T) -> T
 
 **Description:** Bitwise OR `lhs` and `rhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 
 ___
 
@@ -238,7 +238,7 @@ __xor<T>(lhs: T, rhs: T) -> T
 
 **Description:** Bitwise XOR `lhs` and `rhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 ___
 
 ```sway
@@ -247,7 +247,7 @@ __mod<T>(lhs: T, rhs: T) -> T
 
 **Description:** Modulo of `lhs` by `rhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`.
 ___
 
 ```sway
@@ -256,7 +256,7 @@ __rsh<T>(lhs: T, rhs: u64) -> T
 
 **Description:** Logical right shift of `lhs` by `rhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 ___
 
 ```sway
@@ -265,7 +265,7 @@ __lsh<T>(lhs: T, rhs: u64) -> T
 
 **Description:** Logical left shift of `lhs` by `rhs`.
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 ___
 
 ```sway
@@ -314,5 +314,5 @@ __not(op: T) -> T
 
 **Description:** Bitwise NOT of `op`
 
-**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`.
+**Constraints:** `T` is an integer type, i.e. `u8`, `u16`, `u32`, `u64`, `u256`, `b256`.
 ___
diff --git a/docs/book/src/reference/solidity_differences.md b/docs/book/src/reference/solidity_differences.md
@@ -8,11 +8,11 @@ The underlying virtual machine targeted by Sway is the FuelVM, specified [here](
 
 ## Word Size
 
-Words in the FuelVM are 64 bits (8 bytes), rather than the 256 bits (32 bytes) of the EVM. Therefore, primitive integers only go up to `u64`, and hashes (the `b256` type) are not in registers but rather in memory. A `b256` is therefore a pointer to a 32-byte memory region containing the hash value.
+Words in the FuelVM are 64 bits (8 bytes), rather than the 256 bits (32 bytes) of the EVM. Therefore, all primitive integers smaller and including `u64` are stored in registers; `u256`, being bigger than the registers, and hashes (the `b256` type) are not stored in registers but rather in memory. They are therefore pointers to a 32-byte memory region containing the their data.
 
 ## Unsigned Integers Only
 
-Only unsigned integers are provided as primitives: `u8`, `u16`, `u32`, and `u64`. Signed integer arithmetic is not available in the FuelVM. Signed integers and signed integer arithmetic can be implemented in high-level libraries if needed.
+Only unsigned integers are provided as primitives: `u8`, `u16`, `u32`, `u64`, and `u256`. Signed integer arithmetic is not available in the FuelVM. Signed integers and signed integer arithmetic can be implemented in high-level libraries if needed.
 
 ## Global Revert
 

diff --git a/docs/reference/src/documentation/language/built-ins/index.md b/docs/reference/src/documentation/language/built-ins/index.md
@@ -13,7 +13,8 @@ Sway has the following primitive types:
    2. `u16` (16-bit unsigned integer)
    3. `u32` (32-bit unsigned integer)
    4. `u64` (64-bit unsigned integer)
-   5. `hexadecimal`, `binary` & `base-10` syntax
+   5. `u256` (256-bit unsigned integer)
+   6. `hexadecimal`, `binary` & `base-10` syntax
 2. [Boolean](boolean.md)
    1. `bool` (true or false)
 3. [Strings](string.md)

diff --git a/docs/reference/src/documentation/operations/log.md b/docs/reference/src/documentation/operations/log.md
@@ -9,7 +9,7 @@ Each call to `log` appends 1 of 2 types of a [`receipt`](https://fuellabs.github
 - [`Log`](https://fuellabs.github.io/fuel-specs/master/protocol/abi/receipts.html#log-receipt)
   - Generated for _non-reference_ types: `bool`, `u8`, `u16`, `u32`, and `u64`
 - [`LogData`](https://fuellabs.github.io/fuel-specs/master/protocol/abi/receipts.html#logdata-receipt)
-  - Generated for _reference_ types
+  - Generated for _reference_ types and `u256`
 
 The [Rust](https://fuellabs.github.io/fuels-rs/latest/) & [Typescript](https://fuellabs.github.io/fuels-ts/) SDKs may be used to decode the data.
 

diff --git a/test/src/e2e_vm_tests/mod.rs b/test/src/e2e_vm_tests/mod.rs
@@ -76,6 +76,15 @@ struct TestContext {
     deployed_contracts: Arc<Mutex<HashMap<String, ContractId>>>,
 }
 
+fn print_receipt(receipt: &Receipt) {
+    if let Receipt::ReturnData {
+        data: Some(data), ..
+    } = receipt
+    {
+        println!("Data: {:?}", data);
+    }
+}
+
 impl TestContext {
     async fn deploy_contract(&self, contract_path: String) -> Result<ContractId> {
         let mut deployed_contracts = self.deployed_contracts.lock().await;
@@ -90,7 +99,7 @@ impl TestContext {
             },
         )
     }
-    async fn run(&self, test: TestDescription, output: &mut String) -> Result<()> {
+    async fn run(&self, test: TestDescription, output: &mut String, verbose: bool) -> Result<()> {
         let context = self;
         let TestDescription {
             name,
@@ -143,6 +152,12 @@ impl TestContext {
                 let result = harness::runs_in_vm(compiled.clone(), script_data)?;
                 let result = match result {
                     harness::VMExecutionResult::Fuel(state, receipts) => {
+                        if verbose {
+                            for receipt in receipts.iter() {
+                                print_receipt(receipt);
+                            }
+                        }
+
                         match state {
                             ProgramState::Return(v) => TestResult::Return(v),
                             ProgramState::ReturnData(digest) => {
@@ -320,24 +335,27 @@ impl TestContext {
                 *output = out;
 
                 result.map(|tested_pkgs| {
-                    let failed: Vec<String> = tested_pkgs
-                        .into_iter()
-                        .flat_map(|tested_pkg| {
-                            tested_pkg
-                                .tests
-                                .into_iter()
-                                .filter(|test| !test.passed())
-                                .map(move |test| {
-                                    format!(
-                                        "{}: Test '{}' failed with state {:?}, expected: {:?}",
-                                        tested_pkg.built.descriptor.name,
-                                        test.name,
-                                        test.state,
-                                        test.condition,
-                                    )
-                                })
-                        })
-                        .collect();
+                    let mut failed = vec![];
+                    for pkg in tested_pkgs {
+                        for test in pkg.tests.into_iter() {
+                            if verbose {
+                                println!("Test: {} {}", test.name, test.passed());
+                                for log in test.logs.iter() {
+                                    println!("{:?}", log);
+                                }
+                            }
+
+                            if !test.passed() {
+                                failed.push(format!(
+                                    "{}: Test '{}' failed with state {:?}, expected: {:?}",
+                                    pkg.built.descriptor.name,
+                                    test.name,
+                                    test.state,
+                                    test.condition,
+                                ));
+                            }
+                        }
+                    }
 
                     if !failed.is_empty() {
                         println!("FAILED!! output:\n{}", output);
@@ -423,11 +441,11 @@ pub async fn run(filter_config: &FilterConfig, run_config: &RunConfig) -> Result
 
         let result = if !filter_config.first_only {
             context
-                .run(test, &mut output)
+                .run(test, &mut output, run_config.verbose)
                 .instrument(tracing::trace_span!("E2E", i))
                 .await
         } else {
-            context.run(test, &mut output).await
+            context.run(test, &mut output, run_config.verbose).await
         };
 
         if let Err(err) = result {

diff --git a/.../test_programs/should_fail/u256/Forc.lock → ...fail/u256/u256_only_hex_literal/Forc.lock b/.../test_programs/should_fail/u256/Forc.lock → ...fail/u256/u256_only_hex_literal/Forc.lock
diff --git a/...grams/should_pass/language/u256/Forc.toml → ...fail/u256/u256_only_hex_literal/Forc.toml b/...grams/should_pass/language/u256/Forc.toml → ...fail/u256/u256_only_hex_literal/Forc.toml
diff --git a/...est_programs/should_fail/u256/src/main.sw → ...il/u256/u256_only_hex_literal/src/main.sw b/...est_programs/should_fail/u256/src/main.sw → ...il/u256/u256_only_hex_literal/src/main.sw
diff --git a/.../test_programs/should_fail/u256/test.toml → ...fail/u256/u256_only_hex_literal/test.toml b/.../test_programs/should_fail/u256/test.toml → ...fail/u256/u256_only_hex_literal/test.toml
diff --git a/...grams/should_pass/language/u256/Forc.lock → ...uld_pass/language/u256/u256_abi/Forc.lock b/...grams/should_pass/language/u256/Forc.lock → ...uld_pass/language/u256/u256_abi/Forc.lock
diff --git a/.../test_programs/should_fail/u256/Forc.toml → ...uld_pass/language/u256/u256_abi/Forc.toml b/.../test_programs/should_fail/u256/Forc.toml → ...uld_pass/language/u256/u256_abi/Forc.toml
@@ -5,4 +5,4 @@ license = "Apache-2.0"
 name = "ops"
 
 [dependencies]
-std = { path = "../../../../../../sway-lib-std" }
+std = { path = "../../../../../../../../sway-lib-std" }
diff --git a/test/src/e2e_vm_tests/test_programs/should_pass/language/u256/u256_abi/json_abi_oracle.json b/test/src/e2e_vm_tests/test_programs/should_pass/language/u256/u256_abi/json_abi_oracle.json
@@ -0,0 +1,34 @@
+{
+  "configurables": [],
+  "functions": [
+    {
+      "attributes": null,
+      "inputs": [],
+      "name": "main",
+      "output": {
+        "name": "",
+        "type": 0,
+        "typeArguments": null
+      }
+    }
+  ],
+  "loggedTypes": [
+    {
+      "logId": 0,
+      "loggedType": {
+        "name": "",
+        "type": 0,
+        "typeArguments": null
+      }
+    }
+  ],
+  "messagesTypes": [],
+  "types": [
+    {
+      "components": null,
+      "type": "u256",
+      "typeId": 0,
+      "typeParameters": null
+    }
+  ]
+}
diff --git a/test/src/e2e_vm_tests/test_programs/should_pass/language/u256/u256_abi/src/main.sw b/test/src/e2e_vm_tests/test_programs/should_pass/language/u256/u256_abi/src/main.sw
@@ -0,0 +1,6 @@
+script; 
+
+fn main() -> u256 {
+    log(0x00000000000000000000000000000000000000000000000000000002u256);
+    0x00000000000000000000000000000000000000000000000000000001u256
+}
diff --git a/...grams/should_pass/language/u256/test.toml → ...uld_pass/language/u256/u256_abi/test.toml b/...grams/should_pass/language/u256/test.toml → ...uld_pass/language/u256/u256_abi/test.toml
@@ -1,3 +1,3 @@
 category = "run"
-expected_result = { action = "return_data", value = "0000000000000000000000000000000000000000000000000000000000000017" }
+expected_result = { action = "return_data", value = "0000000000000000000000000000000000000000000000000000000000000001" }
 validate_abi = true
diff --git a/test/src/e2e_vm_tests/test_programs/should_pass/language/u256/u256_operators/Forc.lock b/test/src/e2e_vm_tests/test_programs/should_pass/language/u256/u256_operators/Forc.lock
@@ -0,0 +1,13 @@
+[[package]]
+name = 'core'
+source = 'path+from-root-969A3D730A6A09C1'
+
+[[package]]
+name = 'ops'
+source = 'member'
+dependencies = ['std']
+
+[[package]]
+name = 'std'
+source = 'path+from-root-969A3D730A6A09C1'
+dependencies = ['core']
diff --git a/test/src/e2e_vm_tests/test_programs/should_pass/language/u256/u256_operators/Forc.toml b/test/src/e2e_vm_tests/test_programs/should_pass/language/u256/u256_operators/Forc.toml
@@ -0,0 +1,8 @@
+[project]
+authors = ["Fuel Labs <[email protected]>"]
+entry = "main.sw"
+license = "Apache-2.0"
+name = "ops"
+
+[dependencies]
+std = { path = "../../../../../../../../sway-lib-std" }
diff --git a/...d_pass/language/u256/json_abi_oracle.json → .../u256/u256_operators/json_abi_oracle.json b/...d_pass/language/u256/json_abi_oracle.json → .../u256/u256_operators/json_abi_oracle.json