pow_sha256/README.md
Aravinth Manivannan bd570eb12c
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
feat: migrate to git.batsense.net/mcaptcha/pow_sha256
2023-10-14 23:40:57 +05:30

162 lines
4.2 KiB
Markdown

<div align="center">
<h1>PoW-SHA256</h1>
<p>
<strong>PoW-SHA256 - SHA256 based Proof-of-Work</strong>
</p>
[![status-badge](https://ci.batsense.net/api/badges/99/status.svg)](https://ci.batsense.net/repos/99)
</div>
**NOTE: All versions prior to 0.3.1 produce broken PoWs, upgrade to
latest version**
> pow_sha256's copy of `pow_sha256` by
> [robkorn](https://github.com/robkorn/pow_sha256)
> which is a modified version of [`pow` library](https://github.com/bddap/pow).
> All copyrights belong to the original authors.
Rust crate which generates SHA256 Proofs of Work on serializable datatypes.
Whether for blockchain-related projects or Hashcash-like schemes, this
crate can be used to prove work was done on a given serializable input.
The input merely needs to implement `serde::Deserialize` to be used.
This is a fork of the [`pow` library](https://github.com/bddap/pow) by
[@robkorn](https://github.com/robkorn/pow_sha256)) with some new
additions. Primary of these being:
- PoW datatype now offers a constructor
- Salt is no longer hard coded into the library, users can provide
unique salts.
Other small changes have also been included of various importance but
mostly just stylistic/ease of use improvements.
## Documentation
- [master-branch](https://mcaptcha.github.io/pow_sha256/pow_sha256/index.html)
- [All published versions](https://mcaptcha.org/docs/api/pow-sha256)
## Examples
Prove work specifically targeting a phrase.
```rust
use pow_sha256::{ConfigBuilder, PoW};
fn main() {
let config = ConfigBuilder::default()
.salt("myrandomsaltisnotlongenoug".into())
.build()
.unwrap();
let phrase = "ironmansucks";
const DIFFICULTY: u32 = 1000;
let work = config.prove_work(&phrase, DIFFICULTY).unwrap();
assert!(config.calculate(&work, &phrase).unwrap() >= DIFFICULTY);
assert!(config.is_valid_proof(&work, &phrase));
assert!(config.is_sufficient_difficulty(&work, DIFFICULTY));
}
```
Prove more difficult work. This time targeting a time.
```rust
// Greater difficulty this time around. Takes around 100,000 hashes
// to find a nonce of the correct difficulty.
use pow_sha256::{ConfigBuilder, PoW};
fn main() {
let config = ConfigBuilder::default()
.salt("myrandomsaltisnotlongenoug".into())
.build()
.unwrap();
let phrase = "ironmansucks";
const DIFFICULTY: u32 = 100_000;
let work = config.prove_work(&phrase, DIFFICULTY).unwrap();
assert!(config.calculate(&work, &phrase).unwrap() >= DIFFICULTY);
assert!(config.is_valid_proof(&work, &phrase));
assert!(config.is_sufficient_difficulty(&work, DIFFICULTY));
}
```
## Hashing Scheme
`SALT` is used as prefix to prevent PoW reuse from other systems such as
proof of work blockchains.
SHA256 is calculated over the concatenation of the:
- SALT
- Serialized Input `T`
- Nonce
The first 16 bytes of the resulting hash are interpreted as a 128 bit
unsigned integer and saved as the final result.
## Choosing a difficulty setting.
Depending on your use case, difficulty settings often are best set
dynamically a la bitcoin.
However if your use case requires manual setting then it is trivial to
set one yourself. One way to do so is to choose the average number of
hashes desired with a function like this:
```rust
fn get_difficulty(average: u128) -> u128 {
debug_assert_ne!(average, 0, "It is impossible to prove work in zero attempts.");
let m = u128::max_value();
m - m / average
}
```
Conversely we can use the same equation to calculate the probable number
of hashes required to satisfy a given difficulty:
```rust
fn est_average(difficulty: u128) -> u128 {
let m = u128::max_value();
if difficulty == m {
return m;
}
m / (m - difficulty)
}
```
## Changelog
See [CHANGELOG.md](./CHANGELOG.md)
## License
This project is dual-licensed under `Apache License Version 2.0` or `MIT license`.
## Funding
### NLnet
<div align="center">
<img
height="150px"
alt="NLnet NGIZero logo"
src="./docs/third-party/NGIZero-green.hex.svg"
/>
</div>
<br />
2023 development is funded through the [NGI0 Entrust
Fund](https://nlnet.nl/entrust), via [NLnet](https://nlnet.nl/). Please
see [here](https://nlnet.nl/project/mCaptcha/) for more details.