Skip to content

TLA020/rust-proof-fair

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🎲 Provably Fair RNG with HMAC-SHA512 🎲

GitHub Actions Build Status GitHub Actions Test Status

This code implements a provably fair random number generator (RNG) using HMAC-SHA512 hash with a server seed, a client seed, and a nonce.

📋 Requirements

This code requires the following dependencies to be installed:

  • rand 🎲 - a Rust crate for random number generation
  • sha2 🔒 - a Rust crate for SHA-256 and SHA-512 hash functions
  • hmac 🔐 - a Rust crate for Hash-based Message Authentication Code (HMAC)

Add the following lines to your Cargo.toml file to include the dependencies:

[dependencies]
rand = "0.8"
sha2 = "0.12"
hmac = "0.7"

📝 Description

⚙️ This code generates random numbers based on the hash of the server seed, client seed, and a nonce value. The server seed is generated by the server and kept secret until the game is over, while the client seed is generated by the client and is also kept secret if there is more than one player for the game. The nonce is incremented by one for each game round, to ensure that each game round is unique and cannot be repeated or manipulated.

⚠️ It's important to note that the nonce should never be predictable or repeatable, and it should be kept secret from players to prevent any attempts to manipulate the game outcome. These combined are used to generate an HMAC-SHA512 hash.

The Proof struct represents the current state of the RNG, and it provides several methods to interact with the RNG, such as new, log_state, roll, calculate, and verify.

The new method creates a new instance of the Proof struct with the provided or random server seed and client seed, and a given nonce value.

The log_state method logs the current state of the Proof struct to the console, including the random number generated from the current state.

The roll method increments the nonce value and calculates the random number for the current state of the Proof struct.

The calculate method calculates the random number for the current state of the Proof struct, without modifying its state.

The verify method verifies that the provided random number is valid for the given client seed, server seed, and nonce values.

🚀 Example Usage

To use this code, simply create a new instance of the Proof struct with the desired or random server seed, client seed, and nonce values. Then, use the roll or calculate methods to generate random numbers, and use the verify method to verify the validity of a given random number.

use hmac_rng::Proof;

// Create a new Proof instance with a random server seed and client seed, and a nonce value of 0
let mut proof = Proof::new(None, None, 0);

// Log the current state of the Proof instance
proof.log_state();

// Roll the Proof instance to generate a new random number
let result = proof.roll();
match result {
    Ok(random_number) => println!("Random number: {}", random_number),
    Err(err) => eprintln!("Error: {}", err),
}

// Verify the validity of a given random number
let client_seed = vec![1, 2, 3];
let server_seed = vec![4, 5, 6];
let nonce = 0;
let random_number = 0.42;
let result = Proof::verify(&client_seed, Some(&server_seed), nonce, random_number);
match result {
    Ok(valid) => println!("Valid: {}", valid),
    Err(err) => eprintln!("Error: {}", err),
}

🔗 verifier << users can use this to verify