Feat: generate random felt

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Forge
+
+#### Added
+
+- `generate_random_felt()` for generating (pseudo) random felt value.
+
 ### Cast
 
 #### Added

crates/cheatnet/Cargo.toml

@@ -43,6 +43,7 @@ universal-sierra-compiler-api = { path = "../universal-sierra-compiler-api" }
 k256.workspace = true
 p256.workspace = true
 shared.workspace = true
+rand.workspace = true
 
 [dev-dependencies]
 ctor.workspace = true

crates/cheatnet/src/runtime_extensions/forge_runtime_extension/cheatcodes/generate_random_felt.rs

@@ -0,0 +1,10 @@
+use cairo_vm::Felt252;
+use num_bigint::{BigUint, RandBigInt};
+
+#[must_use]
+pub fn generate_random_felt() -> Felt252 {
+    let mut rng = rand::thread_rng();
+
+    let random_number: BigUint = rng.gen_biguint(251);
+    Felt252::from(random_number)
+}

crates/cheatnet/src/runtime_extensions/forge_runtime_extension/cheatcodes/mod.rs

@@ -10,6 +10,7 @@ pub mod cheat_execution_info;
 pub mod cheat_sequencer_address;
 pub mod declare;
 pub mod deploy;
+pub mod generate_random_felt;
 pub mod get_class_hash;
 pub mod l1_handler_execute;
 pub mod mock_call;

crates/cheatnet/src/runtime_extensions/forge_runtime_extension/mod.rs

@@ -10,6 +10,7 @@ use crate::runtime_extensions::{
     forge_runtime_extension::cheatcodes::{
         declare::declare,
         deploy::{deploy, deploy_at},
+        generate_random_felt::generate_random_felt,
         get_class_hash::get_class_hash,
         l1_handler_execute::l1_handler_execute,
         storage::{calculate_variable_address, load, store},
@@ -473,6 +474,9 @@ impl<'a> ExtensionLogic for ForgeExtension<'a> {
                     map_entry_address,
                 ))
             }
+            "generate_random_felt" => Ok(CheatcodeHandlingResult::from_serializable(
+                generate_random_felt(),
+            )),
             _ => Ok(CheatcodeHandlingResult::Forwarded),
         }
     }

crates/cheatnet/tests/cheatcodes/generate_random_felt.rs

@@ -0,0 +1,23 @@
+use cairo_vm::Felt252;
+use std::collections::HashSet;
+
+use cheatnet::runtime_extensions::forge_runtime_extension::cheatcodes::generate_random_felt::generate_random_felt;
+
+#[test]
+fn test_generate_random_felt_range_and_uniqueness() {
+    let mut random_values = vec![];
+
+    let max_felt: Felt252 = Felt252::MAX;
+
+    for _ in 0..10 {
+        let random_value = generate_random_felt();
+        assert!(random_value < max_felt, "Value out of range");
+        random_values.push(random_value);
+    }
+
+    let unique_values: HashSet<_> = random_values.iter().collect();
+    assert!(
+        unique_values.len() > 1,
+        "Random values should not all be identical."
+    );
+}

crates/cheatnet/tests/cheatcodes/mod.rs

@@ -12,6 +12,7 @@ mod cheat_execution_info;
 mod cheat_sequencer_address;
 mod declare;
 mod deploy;
+mod generate_random_felt;
 mod get_class_hash;
 mod load;
 mod mock_call;

crates/forge/tests/integration/generate_random_felt.rs

@@ -0,0 +1,43 @@
+use indoc::indoc;
+use test_utils::runner::assert_passed;
+use test_utils::running_tests::run_test_case;
+use test_utils::test_case;
+
+#[test]
+fn simple_generate_random_felt() {
+    let test = test_case!(indoc!(
+        r"
+        use snforge_std::generate_random_felt;
+
+        #[test]
+        fn simple_generate_random_felt() {
+            let mut random_values = array![];
+            let mut unique_values = array![];
+            let mut i = 10;
+
+        while i != 0 {
+            let random_value = generate_random_felt();
+            random_values.append(random_value);
+            i -= 1;
+        };
+
+        for element in random_values.span() {
+            let mut k = 0; 
+
+            while k != random_values.len() {
+                if element != random_values.at(k) {
+                    unique_values.append(element);
+                };
+                k += 1;
+            };
+        };
+
+        assert(unique_values.len() > 1, 'Identical values');
+        }
+        "
+    ),);
+
+    let result = run_test_case(&test);
+
+    assert_passed(&result);
+}

crates/forge/tests/integration/mod.rs

@@ -13,6 +13,7 @@ mod dispatchers;
 mod env;
 mod fuzzing;
 mod gas;
+mod generate_random_felt;
 mod get_class_hash;
 mod l1_handler_executor;
 mod message_to_l1;

docs/src/SUMMARY.md

@@ -95,6 +95,7 @@
     * [spy_messages_to_l1](appendix/cheatcodes/spy_messages_to_l1.md)
     * [store](appendix/cheatcodes/store.md)
     * [load](appendix/cheatcodes/load.md)
+    * [generate_random_felt](appendix/cheatcodes/generate_random_felt.md)
 * [`snforge` Library Reference](appendix/snforge-library.md)
     * [byte_array](appendix/snforge-library/byte_array.md)
     * [declare](appendix/snforge-library/declare.md)

docs/src/appendix/cheatcodes/generate_random_felt.md

@@ -0,0 +1,5 @@
+# `generate_random_felt`
+
+> `fn generate_random_felt() -> Felt252`
+
+Generates a (pseudo) random `Felt252` value.

snforge_std/src/cheatcodes.cairo

@@ -10,6 +10,7 @@ mod fork;
 mod storage;
 mod execution_info;
 mod message_to_l1;
+mod generate_random_felt;
 
 /// Enum used to specify how long the target should be cheated for.
 #[derive(Copy, Drop, Serde, PartialEq, Clone, Debug)]

snforge_std/src/cheatcodes/generate_random_felt.cairo

@@ -0,0 +1,13 @@
+use starknet::testing::cheatcode;
+use core::serde::Serde;
+use super::super::_cheatcode::handle_cheatcode;
+
+
+/// Generates a random felt value
+///
+/// Returns a random felt within the range of 0 and 2^252 - 1
+fn generate_random_felt() -> felt252 {
+    let mut random_felt = handle_cheatcode(cheatcode::<'generate_random_felt'>(array![].span()));
+
+    Serde::deserialize(ref random_felt).unwrap()
+}

snforge_std/src/lib.cairo

@@ -130,6 +130,8 @@ use cheatcodes::execution_info::account_contract_address::stop_cheat_account_con
 use cheatcodes::execution_info::account_contract_address::stop_cheat_account_contract_address_global;
 use cheatcodes::execution_info::account_contract_address::start_cheat_account_contract_address;
 
+use cheatcodes::generate_random_felt::generate_random_felt;
+
 
 mod fs;