chore: format and standardize all markdowns files
according to the github flavor (https://github.github.com/gfm/)
This commit is contained in:
parent
c4d017e7c4
commit
b355740da4
|
@ -1,5 +1,4 @@
|
||||||
Bitcoin base58 encoding
|
# Bitcoin base58 encoding
|
||||||
=======================
|
|
||||||
|
|
||||||
This crate provides encoding and decoding of base58 strings as defined by the Bitcoin ecosystem
|
This crate provides encoding and decoding of base58 strings as defined by the Bitcoin ecosystem
|
||||||
including the checksum.
|
including the checksum.
|
||||||
|
@ -21,12 +20,10 @@ obviously named ones differ from this crate because:
|
||||||
This crate uses [bitcoin_hashes](https://crates.io/crates/bitcoin_hashes) when hashing to calculate
|
This crate uses [bitcoin_hashes](https://crates.io/crates/bitcoin_hashes) when hashing to calculate
|
||||||
the checksum.
|
the checksum.
|
||||||
|
|
||||||
|
|
||||||
## Minimum Supported Rust Version (MSRV)
|
## Minimum Supported Rust Version (MSRV)
|
||||||
|
|
||||||
This library should always compile with any combination of features on **Rust 1.56.1**.
|
This library should always compile with any combination of features on **Rust 1.56.1**.
|
||||||
|
|
||||||
|
|
||||||
## Licensing
|
## Licensing
|
||||||
|
|
||||||
The code in this project is licensed under the [Creative Commons CC0 1.0 Universal license](LICENSE).
|
The code in this project is licensed under the [Creative Commons CC0 1.0 Universal license](LICENSE).
|
||||||
|
|
|
@ -1,4 +1,3 @@
|
||||||
Test vector data
|
# Test vector data
|
||||||
================
|
|
||||||
|
|
||||||
This file contains data (hex strings) taken from BIP test vectors.
|
This file contains data (hex strings) taken from BIP test vectors.
|
||||||
|
|
|
@ -1,12 +1,11 @@
|
||||||
Serialization input/output
|
# Serialization input/output
|
||||||
==========================
|
|
||||||
|
|
||||||
Files here contain hex strings and binary data representing types used for
|
Files here contain hex strings and binary data representing types used for
|
||||||
regression testing.
|
regression testing.
|
||||||
|
|
||||||
- *_hex: consensus encoded types represented as hex strings
|
- `*_hex`: consensus encoded types represented as hex strings
|
||||||
- *_ser: consensus encoded types represented as binary data
|
- `*_ser`: consensus encoded types represented as binary data
|
||||||
- *_bincode: types serialized with serde as bincode
|
- `*_bincode`: types serialized with `serde` as bincode
|
||||||
|
|
||||||
We consensus deserialize, serde serialize, then check against the expected data
|
We consensus deserialize, `serde` serialize, then check against the expected data
|
||||||
to verify no serde regressions have been introduced.
|
to verify no `serde` regressions have been introduced.
|
||||||
|
|
|
@ -6,7 +6,9 @@ honggfuzz.
|
||||||
To run the fuzz-tests as in CI -- briefly fuzzing every target -- simply
|
To run the fuzz-tests as in CI -- briefly fuzzing every target -- simply
|
||||||
run
|
run
|
||||||
|
|
||||||
./fuzz.sh
|
```bash
|
||||||
|
./fuzz.sh
|
||||||
|
```
|
||||||
|
|
||||||
in this directory.
|
in this directory.
|
||||||
|
|
||||||
|
@ -16,11 +18,13 @@ recently-released binutils 2.39 has changed their API in a breaking way.
|
||||||
|
|
||||||
On Nix, you can obtain these libraries by running
|
On Nix, you can obtain these libraries by running
|
||||||
|
|
||||||
nix-shell -p libopcodes_2_38 -p libunwind
|
```bash
|
||||||
|
nix-shell -p libopcodes_2_38 -p libunwind
|
||||||
|
```
|
||||||
|
|
||||||
and then run fuzz.sh as above.
|
and then run `fuzz.sh` as above.
|
||||||
|
|
||||||
# Fuzzing with weak cryptography
|
## Fuzzing with weak cryptography
|
||||||
|
|
||||||
You may wish to replace the hashing and signing code with broken crypto,
|
You may wish to replace the hashing and signing code with broken crypto,
|
||||||
which will be faster and enable the fuzzer to do otherwise impossible
|
which will be faster and enable the fuzzer to do otherwise impossible
|
||||||
|
@ -35,35 +39,43 @@ Please let us know if you are interested in taking this on!
|
||||||
Meanwhile, to use the broken crypto, simply compile (and run the fuzzing
|
Meanwhile, to use the broken crypto, simply compile (and run the fuzzing
|
||||||
scripts) with
|
scripts) with
|
||||||
|
|
||||||
RUSTFLAGS="--cfg=hashes_fuzz --cfg=secp256k1_fuzz"
|
```bash
|
||||||
|
RUSTFLAGS="--cfg=hashes_fuzz --cfg=secp256k1_fuzz"
|
||||||
|
```
|
||||||
|
|
||||||
which will replace the hashing library with broken hashes, and the
|
which will replace the hashing library with broken hashes, and the
|
||||||
secp256k1 library with broken cryptography.
|
`secp256k1` library with broken cryptography.
|
||||||
|
|
||||||
Needless to say, NEVER COMPILE REAL CODE WITH THESE FLAGS because if a
|
Needless to say, NEVER COMPILE REAL CODE WITH THESE FLAGS because if a
|
||||||
fuzzer can break your crypto, so can anybody.
|
fuzzer can break your crypto, so can anybody.
|
||||||
|
|
||||||
# Long-term fuzzing
|
## Long-term fuzzing
|
||||||
|
|
||||||
To see the full list of targets, the most straightforward way is to run
|
To see the full list of targets, the most straightforward way is to run
|
||||||
|
|
||||||
source ./fuzz-util.sh
|
```bash
|
||||||
listTargetNames
|
source ./fuzz-util.sh
|
||||||
|
listTargetNames
|
||||||
|
```
|
||||||
|
|
||||||
To run each of them for an hour, run
|
To run each of them for an hour, run
|
||||||
|
|
||||||
./cycle.sh
|
```bash
|
||||||
|
./cycle.sh
|
||||||
|
```
|
||||||
|
|
||||||
To run a single fuzztest indefinitely, run
|
To run a single fuzztest indefinitely, run
|
||||||
|
|
||||||
HFUZZ_BUILD_ARGS='--features honggfuzz_fuzz' cargo hfuzz run <target>
|
```bash
|
||||||
|
HFUZZ_BUILD_ARGS='--features honggfuzz_fuzz' cargo hfuzz run <target>
|
||||||
|
```
|
||||||
|
|
||||||
This script uses the `chrt` utility to try to reduce the priority of the
|
This script uses the `chrt` utility to try to reduce the priority of the
|
||||||
jobs. If you would like to run for longer, the most straightforward way
|
jobs. If you would like to run for longer, the most straightforward way
|
||||||
is to edit `cycle.sh` before starting. To run the fuzz-tests in parallel,
|
is to edit `cycle.sh` before starting. To run the fuzz-tests in parallel,
|
||||||
you will need to implement a custom harness.
|
you will need to implement a custom harness.
|
||||||
|
|
||||||
# Adding fuzz tests
|
## Adding fuzz tests
|
||||||
|
|
||||||
All fuzz tests can be found in the `fuzz_target/` directory. Adding a new
|
All fuzz tests can be found in the `fuzz_target/` directory. Adding a new
|
||||||
one is as simple as copying an existing one and editing the `do_test`
|
one is as simple as copying an existing one and editing the `do_test`
|
||||||
|
@ -78,21 +90,25 @@ it to the generated `Cargo.toml`.
|
||||||
Once you've added a fuzztest, regenerate the `Cargo.toml` and CI job by
|
Once you've added a fuzztest, regenerate the `Cargo.toml` and CI job by
|
||||||
running
|
running
|
||||||
|
|
||||||
./generate-files.sh
|
```bash
|
||||||
|
./generate-files.sh
|
||||||
|
```
|
||||||
|
|
||||||
Then to test your fuzztest, run
|
Then to test your fuzztest, run
|
||||||
|
|
||||||
./fuzz.sh <target>
|
```bash
|
||||||
|
./fuzz.sh <target>
|
||||||
|
```
|
||||||
|
|
||||||
If it is working, you will see a rapid stream of data for many seconds
|
If it is working, you will see a rapid stream of data for many seconds
|
||||||
(you can hit Ctrl+C to stop it early). If not, you should quickly see
|
(you can hit Ctrl+C to stop it early). If not, you should quickly see
|
||||||
an error.
|
an error.
|
||||||
|
|
||||||
# Reproducing Failures
|
## Reproducing Failures
|
||||||
|
|
||||||
If a fuzztest fails, it will exit with a summary which looks something like
|
If a fuzztest fails, it will exit with a summary which looks something like
|
||||||
|
|
||||||
```
|
```text
|
||||||
...
|
...
|
||||||
fuzzTarget : hfuzz_target/x86_64-unknown-linux-gnu/release/hashes_sha256
|
fuzzTarget : hfuzz_target/x86_64-unknown-linux-gnu/release/hashes_sha256
|
||||||
CRASH:
|
CRASH:
|
||||||
|
@ -108,8 +124,9 @@ The final line is a hex-encoded version of the input that caused the crash. You
|
||||||
can test this directly by editing the `duplicate_crash` test to copy/paste the
|
can test this directly by editing the `duplicate_crash` test to copy/paste the
|
||||||
hex output into the call to `extend_vec_from_hex`. Then run the test with
|
hex output into the call to `extend_vec_from_hex`. Then run the test with
|
||||||
|
|
||||||
cargo test
|
```bash
|
||||||
|
cargo test
|
||||||
|
```
|
||||||
|
|
||||||
Note that if you set your `RUSTFLAGS` while fuzzing (see above) you must make
|
Note that if you set your `RUSTFLAGS` while fuzzing (see above) you must make
|
||||||
sure they are set the same way when running `cargo test`.
|
sure they are set the same way when running `cargo test`.
|
||||||
|
|
||||||
|
|
|
@ -20,7 +20,8 @@ Contributions are welcome, including additional hash function implementations.
|
||||||
To assist devs in catching errors _before_ running CI we provide some githooks. If you do not
|
To assist devs in catching errors _before_ running CI we provide some githooks. If you do not
|
||||||
already have locally configured githooks you can use the ones in this repository by running, in the
|
already have locally configured githooks you can use the ones in this repository by running, in the
|
||||||
root directory of the repository:
|
root directory of the repository:
|
||||||
```
|
|
||||||
|
```bash
|
||||||
git config --local core.hooksPath githooks/
|
git config --local core.hooksPath githooks/
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
@ -6,6 +6,8 @@ Run as usual with `cargo test`.
|
||||||
|
|
||||||
To run the tests with the MSRV you will need to pin `serde`:
|
To run the tests with the MSRV you will need to pin `serde`:
|
||||||
|
|
||||||
- `cargo update -p serde --precise 1.0.156`
|
```bash
|
||||||
- `cargo update -p regex --precise 1.7.3`
|
cargo update -p serde --precise 1.0.156
|
||||||
- `cargo update -p chrono --precise 0.4.24`
|
cargo update -p regex --precise 1.7.3
|
||||||
|
cargo update -p chrono --precise 0.4.24
|
||||||
|
```
|
||||||
|
|
|
@ -1,5 +1,4 @@
|
||||||
Rust Bitcoin Internals
|
# Rust Bitcoin Internals
|
||||||
======================
|
|
||||||
|
|
||||||
This crate is only meant to be used internally by crates in the
|
This crate is only meant to be used internally by crates in the
|
||||||
[rust-bitcoin](https://github.com/rust-bitcoin) ecosystem.
|
[rust-bitcoin](https://github.com/rust-bitcoin) ecosystem.
|
||||||
|
|
|
@ -1,9 +1,8 @@
|
||||||
Rust-Bitcoin IO Library
|
# Rust-Bitcoin IO Library
|
||||||
=======================
|
|
||||||
|
|
||||||
The `std::io` module is not exposed in `no-std` Rust so building `no-std` applications which require
|
The `std::io` module is not exposed in `no-std` Rust so building `no-std` applications which require
|
||||||
reading and writing objects via standard traits is not generally possible. Thus, this library exists
|
reading and writing objects via standard traits is not generally possible. Thus, this library exists
|
||||||
to export a minmal version of `std::io`'s traits which we use in `rust-bitcoin` so that we can
|
to export a minimal version of `std::io`'s traits which we use in `rust-bitcoin` so that we can
|
||||||
support `no-std` applications.
|
support `no-std` applications.
|
||||||
|
|
||||||
These traits are not one-for-one drop-ins, but are as close as possible while still implementing
|
These traits are not one-for-one drop-ins, but are as close as possible while still implementing
|
||||||
|
|
|
@ -23,7 +23,7 @@ Rust Logo is licensed under CC-BY, which allows reuse and modifications for any
|
||||||
|
|
||||||
## Acknowledgements
|
## Acknowledgements
|
||||||
|
|
||||||
Acknowledgement for the runners up in this PR: https://github.com/rust-bitcoin/rust-bitcoin/pull/891#issuecomment-1074476858
|
Acknowledgement for the runners up in this PR: <https://github.com/rust-bitcoin/rust-bitcoin/pull/891#issuecomment-1074476858>
|
||||||
|
|
||||||
In particular, the Rust Bitcoin Wizard gear was an incredibly inspired piece of art. Also, the meshed gears design was beloved by some but not all.
|
In particular, the Rust Bitcoin Wizard gear was an incredibly inspired piece of art. Also, the meshed gears design was beloved by some but not all.
|
||||||
|
|
||||||
|
|
|
@ -1,14 +1,11 @@
|
||||||
Bitcoin Units
|
# Bitcoin Units
|
||||||
=============
|
|
||||||
|
|
||||||
This crate provides basic Bitcoin numeric units such as `Amount`.
|
This crate provides basic Bitcoin numeric units such as `Amount`.
|
||||||
|
|
||||||
|
|
||||||
## Minimum Supported Rust Version (MSRV)
|
## Minimum Supported Rust Version (MSRV)
|
||||||
|
|
||||||
This library should always compile with any combination of features on **Rust 1.56.1**.
|
This library should always compile with any combination of features on **Rust 1.56.1**.
|
||||||
|
|
||||||
|
|
||||||
## Licensing
|
## Licensing
|
||||||
|
|
||||||
The code in this project is licensed under the [Creative Commons CC0 1.0 Universal license](LICENSE).
|
The code in this project is licensed under the [Creative Commons CC0 1.0 Universal license](LICENSE).
|
||||||
|
|
Loading…
Reference in New Issue