POW Account

This library generates a cryptographic hash and performs a second round of hashing to produce a hash with a configurable number of leading zeros. It is designed for applications requiring proof-of-work-like functionality or hash-based validation with adjustable difficulty.

The algorithm of work

The sequence diagram below shows the high-level algorithm of client-server interaction.

sequenceDiagram
    autonumber
    participant c as Client
    participant s as Server

    c ->> c: Generate an origin hash for a target hash with N leading zeros
    c ->> s: Send a request
    s ->> s: Calculates the target hash and checks the number of leading zeros

    alt Correct Target Hash
      s ->> c: Return a response
    else Insufficient number of Leading Zeros
      s ->> c: Return an error
    end

Step 1. A Client generates an origin hash for a target hash that starts with a particular number of zeros. The required number of zeros is defined by the Server.

Step 2. A Client sends the request to the Server (for instance, to get an Auth Token).

Step 3. A Server calculates the target hash and checks if the target hash starts with the proper number of leading zeros.

Step 4. A Server returns a successful response if the number of leading zeros is correct, otherwise returns an error.

Installation

To install the library from your app folder run:

cargo add pow_account

Add required dependencies

cargo add blake2
cargo add hex

Or clone the repository to your app folder and add the following to your Cargo.toml:

[dependencies]
pow_account = { path = "../path/to/pow_account" }
blake2 = "0.10.6"
hex = "0.4.3"

Usage

Here's a brief overview of how to use the library:

Importing the Library

use pow_account::HashFinder;

Generating an Origin Hash for a Target Hash with a default number of Leading Zeros

If you want to generate an origin hash for a target hash with the default number of leading zeros (which is 20 bits or 5 leading zeros), you can do so like this:

use pow_account::HashFinder;

let origin_hash = HashFinder::default().find();
let origin_hash_hex = hex::encode(origin_hash);
println!("Generated origin hash: {}", origin_hash_hex);

Generating an Origin Hash for a Target Hash with a specified number of Leading Zeros

You can create a new HashFinder instance with a specified number of leading zeros and generate an origin hash as follows:

use pow_account::HashFinder;

let origin_hash = HashFinder::new(4).find();
let origin_hash_hex = hex::encode(origin_hash);
println!("Generated origin hash: {}", origin_hash_hex);

This will generate an origin hash for a Target Hash that starts with 4 leading zeros.

Checking that the Target Hash starts with a required number of Leading Zeros

You can check the number of leading zeros for a hash as following:

use pow_account::HashFinder;

let origin_hash = HashFinder::default().find();
let origin_hash_hex = hex::encode(origin_hash);

// Default number of leading zeros
if let Ok(match_result) = HashFinder::default().check(origin_hash_hex) {
    ...
}

let origin_hash = HashFinder::new(4).find();
let origin_hash_hex = hex::encode(origin_hash);

// Custom number of leading zeros
if let Ok(match_result) = HashFinder::new(4).check(origin_hash_hex) {
    ...
}

This will generate an origin hash for a target hash that starts with 4 leading zeros.

Example

Here’s a complete example demonstrating how to generate an origin hash and validate it:

use blake2::{Blake2s256, Digest};
use pow_account::HashFinder;

fn main() {
    // 1. Generating the origin hash (client side)
    let origin_hash = HashFinder::new(4).find();

    // This origin_hash_hex String is the one to be sent to the Server
    let origin_hash_hex = hex::encode(origin_hash);

    // 2. Calculating the target hash (server side)
    let mut hasher = Blake2s256::new();
    hasher.update(&origin_hash);
    let target_hash: [u8; 32] = hasher.finalize().into();

    // This is the target hash that should be started with a specified number of leading zeros
    let target_hash_hex = hex::encode(target_hash);

    assert!(target_hash_hex.starts_with("0000"));
    println!("Generated hash with 4 leading zeros: {}", target_hash_hex);

    // 3. Calculate the taget hash and check that it starts with 4 zeros
    if let Ok(match_result) = HashFinder::new(4).check(origin_hash_hex) {
        println!("Result of match: {}", match_result);

        // 4. Process the result of the match
        match match_result {
            true => {
                // Correct Target Hash
            }
            false => {
                // Insufficient number of Leading Zeros
            }
        }
    }
}

Running Tests

To run the tests included with this library, use the following command in the root directory of your library:

cargo test

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for any suggestions or improvements.

License

This library is licensed under the MIT License. See the LICENSE file for more details.