Random Number Generator

.gitignore

@@ -9,3 +9,4 @@ output
 # Others
 .snfoundry_cache
 .vscode/settings.json
+**/starkli-wallet

Scarb.lock

@@ -28,6 +28,15 @@ version = "0.1.0"
 name = "calling_other_contracts"
 version = "0.1.0"
 
+[[package]]
+name = "coin_flip"
+version = "0.1.0"
+dependencies = [
+ "openzeppelin",
+ "pragma_lib",
+ "snforge_std",
+]
+
 [[package]]
 name = "components"
 version = "0.1.0"
@@ -120,6 +129,11 @@ name = "openzeppelin"
 version = "0.14.0"
 source = "git+https://github.com/OpenZeppelin/cairo-contracts.git?tag=v0.14.0#f091c4f51ddeb10297db984acae965328c5a4e5b"
 
+[[package]]
+name = "pragma_lib"
+version = "1.0.0"
+source = "git+https://github.com/astraly-labs/pragma-lib#2eca9b70dc505788423da1eedbf2d65563cc3102"
+
 [[package]]
 name = "scarb"
 version = "0.1.0"

Scarb.toml

@@ -18,6 +18,7 @@ components = { path = "listings/applications/components" }
 snforge_std = { git = "https://github.com/foundry-rs/starknet-foundry.git", tag = "v0.25.0" }
 # The latest Alexandria release supports only Cairo v2.6.0, so using explicit rev that supports Cairo v2.6.3
 alexandria_storage = { git = "https://github.com/keep-starknet-strange/alexandria.git", rev="800f5ad" }
+pragma_lib = { git = "https://github.com/astraly-labs/pragma-lib" }
 
 [workspace.package]
 description = "Collection of examples of how to use the Cairo programming language to create smart contracts on Starknet."

listings/applications/advanced_factory/src/tests.cairo

@@ -1,5 +1,3 @@
-use core::clone::Clone;
-use core::result::ResultTrait;
 use advanced_factory::contract::{
  CampaignFactory, ICampaignFactoryDispatcher, ICampaignFactoryDispatcherTrait
 };

listings/applications/coin_flip/.gitignore

@@ -0,0 +1,2 @@
+target
+.snfoundry_cache/

listings/applications/coin_flip/Scarb.toml

@@ -0,0 +1,17 @@
+[package]
+name = "coin_flip"
+version = "0.1.0"
+edition = "2023_11"
+
+[dependencies]
+starknet.workspace = true
+openzeppelin.workspace = true
+pragma_lib.workspace = true
+snforge_std.workspace = true
+
+[scripts]
+test.workspace = true
+
+[[target.starknet-contract]]
+casm = true
+build-external-contracts = ["openzeppelin::presets::erc20::ERC20Upgradeable"]

listings/applications/coin_flip/src/contract.cairo

@@ -0,0 +1,169 @@
+use starknet::ContractAddress;
+
+#[starknet::interface]
+pub trait ICoinFlip<TContractState> {
+ fn flip(ref self: TContractState);
+}
+
+// declares just the pragma_lib::abi::IRandomness.receive_random_words function
+#[starknet::interface]
+pub trait IPragmaVRF<TContractState> {
+ fn receive_random_words(
+ ref self: TContractState,
+ requestor_address: ContractAddress,
+ request_id: u64,
+ random_words: Span<felt252>,
+ calldata: Array<felt252>
+ );
+}
+
+#[starknet::contract]
+pub mod CoinFlip {
+ use core::num::traits::zero::Zero;
+ use starknet::{ContractAddress, get_caller_address, get_contract_address,};
+ use pragma_lib::abi::{IRandomnessDispatcher, IRandomnessDispatcherTrait};
+ use openzeppelin::token::erc20::interface::{IERC20Dispatcher, IERC20DispatcherTrait};
+
+ #[storage]
+ struct Storage {
+ eth_dispatcher: IERC20Dispatcher,
+ flips: LegacyMap<u64, ContractAddress>,
+ nonce: u64,
+ randomness_contract_address: ContractAddress,
+ }
+
+ #[event]
+ #[derive(Drop, starknet::Event)]
+ pub enum Event {
+ Flipped: Flipped,
+ Landed: Landed,
+ }
+
+ #[derive(Drop, starknet::Event)]
+ pub struct Flipped {
+ pub flip_id: u64,
+ pub flipper: ContractAddress,
+ }
+
+ #[derive(Drop, starknet::Event)]
+ pub struct Landed {
+ pub flip_id: u64,
+ pub flipper: ContractAddress,
+ pub side: Side
+ }
+
+ #[derive(Drop, Debug, PartialEq, Serde)]
+ pub enum Side {
+ Heads,
+ Tails,
+ }
+
+ pub mod Errors {
+ pub const CALLER_NOT_RANDOMNESS: felt252 = 'Caller not randomness contract';
+ pub const INVALID_ADDRESS: felt252 = 'Invalid address';
+ pub const INVALID_FLIP_ID: felt252 = 'No flip with the given ID';
+ pub const REQUESTOR_NOT_SELF: felt252 = 'Requestor is not self';
+ pub const TRANSFER_FAILED: felt252 = 'Transfer failed';
+ }
+
+ pub const PUBLISH_DELAY: u64 = 1; // return the random value asap
+ pub const NUM_OF_WORDS: u64 = 1; // one random value is sufficient
+ pub const CALLBACK_FEE_LIMIT: u128 = 100_000_000_000_000; // 0.0001 ETH
+ pub const MAX_CALLBACK_FEE_DEPOSIT: u256 =
+ 500_000_000_000_000; // CALLBACK_FEE_LIMIT * 5; needs to cover the Premium fee
+
+ #[constructor]
+ fn constructor(
+ ref self: ContractState,
+ randomness_contract_address: ContractAddress,
+ eth_address: ContractAddress
+ ) {
+ assert(randomness_contract_address.is_non_zero(), Errors::INVALID_ADDRESS);
+ assert(eth_address.is_non_zero(), Errors::INVALID_ADDRESS);
+ self.randomness_contract_address.write(randomness_contract_address);
+ self.eth_dispatcher.write(IERC20Dispatcher { contract_address: eth_address });
+ }
+
+ #[abi(embed_v0)]
+ impl CoinFlip of super::ICoinFlip<ContractState> {
+ /// The contract needs to be funded with some ETH in order for this function
+ /// to be callable. For simplicity, anyone can fund the contract.
+ fn flip(ref self: ContractState) {
+ let flip_id = self._request_my_randomness();
+ let flipper = get_caller_address();
+ self.flips.write(flip_id, flipper);
+ self.emit(Event::Flipped(Flipped { flip_id, flipper }));
+ }
+ }
+
+ #[abi(embed_v0)]
+ impl PragmaVRF of super::IPragmaVRF<ContractState> {
+ fn receive_random_words(
+ ref self: ContractState,
+ requestor_address: ContractAddress,
+ request_id: u64,
+ random_words: Span<felt252>,
+ calldata: Array<felt252>
+ ) {
+ let caller = get_caller_address();
+ assert(
+ caller == self.randomness_contract_address.read(), Errors::CALLER_NOT_RANDOMNESS
+ );
+
+ let this = get_contract_address();
+ assert(requestor_address == this, Errors::REQUESTOR_NOT_SELF);
+
+ self._process_coin_flip(request_id, random_words.at(0));
+ }
+ }
+
+ #[generate_trait]
+ impl Private of PrivateTrait {
+ fn _request_my_randomness(ref self: ContractState) -> u64 {
+ let randomness_contract_address = self.randomness_contract_address.read();
+ let randomness_dispatcher = IRandomnessDispatcher {
+ contract_address: randomness_contract_address
+ };
+
+ let this = get_contract_address();
+
+ // Approve the randomness contract to transfer the callback deposit/fee
+ let eth_dispatcher = self.eth_dispatcher.read();
+ eth_dispatcher.approve(randomness_contract_address, MAX_CALLBACK_FEE_DEPOSIT);
+
+ let nonce = self.nonce.read();
+
+ // Request the randomness to be used to construct the winning combination
+ let request_id = randomness_dispatcher
+ .request_random(
+ nonce, this, CALLBACK_FEE_LIMIT, PUBLISH_DELAY, NUM_OF_WORDS, array![]
+ );
+
+ self.nonce.write(nonce + 1);
+
+ request_id
+ }
+
+ /// The chance of a flipped coin landing sideways is approximately 1 in 6000.
+ /// See paper: https://journals.aps.org/pre/abstract/10.1103/PhysRevE.48.2547
+ /// 
+ /// Since splitting the remainder (5999) equally between heads and tails is impossible,
+ /// we double the probability values:
+ /// - 2 in 12000 chance that it's sideways
+ /// - 5999 in 12000 chance that it's heads
+ /// - 5999 in 12000 chance that it's tails
+ fn _process_coin_flip(ref self: ContractState, flip_id: u64, random_value: @felt252) {
+ let flipper = self.flips.read(flip_id);
+ assert(flipper.is_non_zero(), Errors::INVALID_FLIP_ID);
+
+ let random_value: u256 = (*random_value).into();
+ let side = if random_value % 2 == 0 {
+ Side::Heads
+ } else {
+ Side::Tails
+ };
+
+ self.emit(Event::Landed(Landed { flip_id, flipper, side }));
+ }
+ }
+}

listings/applications/coin_flip/src/lib.cairo

@@ -0,0 +1,5 @@
+mod contract;
+mod mock_randomness;
+
+#[cfg(test)]
+mod tests;