149 lines
4.3 KiB
Markdown
149 lines
4.3 KiB
Markdown
<div align="center">
|
|
<h1>PoW-SHA256</h1>
|
|
<p>
|
|
<strong>PoW-SHA256 - SHA256 based Proof-of-Work</strong>
|
|
</p>
|
|
|
|
[](https://mcaptcha.github.io/pow_sha256/pow_sha256/index.html)
|
|
[](https://mcaptcha.org/docs/api/pow-sha256)
|
|
/badge.svg>)
|
|
[](https://deps.rs/repo/github/mCaptcha/pow_sha256)
|
|
<br />
|
|
[](https://codecov.io/gh/mCaptcha/pow_sha256)
|
|
|
|
</div>
|
|
|
|
**NOTE: All versions prior to 0.2.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`.
|