From b355740da43233958990998bb53b4d6e19069c06 Mon Sep 17 00:00:00 2001 From: Jose Storopoli Date: Sat, 27 Apr 2024 06:29:23 -0300 Subject: [PATCH] chore: format and standardize all markdowns files according to the github flavor (https://github.github.com/gfm/) --- base58/README.md | 5 +-- bitcoin/tests/data/README.md | 3 +- bitcoin/tests/data/serde/README.md | 13 +++--- fuzz/README.md | 53 ++++++++++++++++-------- hashes/README.md | 3 +- hashes/extended_tests/schemars/README.md | 8 ++-- internals/README.md | 3 +- io/README.md | 5 +-- logo/README.md | 2 +- units/README.md | 5 +-- 10 files changed, 55 insertions(+), 45 deletions(-) diff --git a/base58/README.md b/base58/README.md index 211b85744..d69760c5a 100644 --- a/base58/README.md +++ b/base58/README.md @@ -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 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 the checksum. - ## Minimum Supported Rust Version (MSRV) This library should always compile with any combination of features on **Rust 1.56.1**. - ## Licensing The code in this project is licensed under the [Creative Commons CC0 1.0 Universal license](LICENSE). diff --git a/bitcoin/tests/data/README.md b/bitcoin/tests/data/README.md index 70ed7a4ef..0792fd149 100644 --- a/bitcoin/tests/data/README.md +++ b/bitcoin/tests/data/README.md @@ -1,4 +1,3 @@ -Test vector data -================ +# Test vector data This file contains data (hex strings) taken from BIP test vectors. diff --git a/bitcoin/tests/data/serde/README.md b/bitcoin/tests/data/serde/README.md index a12793ba0..4d4a905a6 100644 --- a/bitcoin/tests/data/serde/README.md +++ b/bitcoin/tests/data/serde/README.md @@ -1,12 +1,11 @@ -Serialization input/output -========================== +# Serialization input/output Files here contain hex strings and binary data representing types used for regression testing. -- *_hex: consensus encoded types represented as hex strings -- *_ser: consensus encoded types represented as binary data -- *_bincode: types serialized with serde as bincode +- `*_hex`: consensus encoded types represented as hex strings +- `*_ser`: consensus encoded types represented as binary data +- `*_bincode`: types serialized with `serde` as bincode -We consensus deserialize, serde serialize, then check against the expected data -to verify no serde regressions have been introduced. +We consensus deserialize, `serde` serialize, then check against the expected data +to verify no `serde` regressions have been introduced. diff --git a/fuzz/README.md b/fuzz/README.md index f53a22e43..38b7d8547 100644 --- a/fuzz/README.md +++ b/fuzz/README.md @@ -6,7 +6,9 @@ honggfuzz. To run the fuzz-tests as in CI -- briefly fuzzing every target -- simply run - ./fuzz.sh +```bash +./fuzz.sh +``` 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 - 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, 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 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 -secp256k1 library with broken cryptography. +`secp256k1` library with broken cryptography. Needless to say, NEVER COMPILE REAL CODE WITH THESE FLAGS because if a 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 - source ./fuzz-util.sh - listTargetNames +```bash +source ./fuzz-util.sh +listTargetNames +``` To run each of them for an hour, run - ./cycle.sh +```bash +./cycle.sh +``` To run a single fuzztest indefinitely, run - HFUZZ_BUILD_ARGS='--features honggfuzz_fuzz' cargo hfuzz run +```bash +HFUZZ_BUILD_ARGS='--features honggfuzz_fuzz' cargo hfuzz run +``` 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 is to edit `cycle.sh` before starting. To run the fuzz-tests in parallel, 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 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 running - ./generate-files.sh +```bash +./generate-files.sh +``` Then to test your fuzztest, run - ./fuzz.sh +```bash +./fuzz.sh +``` 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 an error. -# Reproducing Failures +## Reproducing Failures 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 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 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 sure they are set the same way when running `cargo test`. - diff --git a/hashes/README.md b/hashes/README.md index 4ce91fa95..9b342bd1f 100644 --- a/hashes/README.md +++ b/hashes/README.md @@ -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 already have locally configured githooks you can use the ones in this repository by running, in the root directory of the repository: -``` + +```bash git config --local core.hooksPath githooks/ ``` diff --git a/hashes/extended_tests/schemars/README.md b/hashes/extended_tests/schemars/README.md index 9e0a59708..51dc97c42 100644 --- a/hashes/extended_tests/schemars/README.md +++ b/hashes/extended_tests/schemars/README.md @@ -6,6 +6,8 @@ Run as usual with `cargo test`. To run the tests with the MSRV you will need to pin `serde`: -- `cargo update -p serde --precise 1.0.156` -- `cargo update -p regex --precise 1.7.3` -- `cargo update -p chrono --precise 0.4.24` +```bash +cargo update -p serde --precise 1.0.156 +cargo update -p regex --precise 1.7.3 +cargo update -p chrono --precise 0.4.24 +``` diff --git a/internals/README.md b/internals/README.md index 79aa29804..66aae69cd 100644 --- a/internals/README.md +++ b/internals/README.md @@ -1,5 +1,4 @@ -Rust Bitcoin Internals -====================== +# Rust Bitcoin Internals This crate is only meant to be used internally by crates in the [rust-bitcoin](https://github.com/rust-bitcoin) ecosystem. diff --git a/io/README.md b/io/README.md index e38e2d068..f276437bc 100644 --- a/io/README.md +++ b/io/README.md @@ -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 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. These traits are not one-for-one drop-ins, but are as close as possible while still implementing diff --git a/logo/README.md b/logo/README.md index 71a563dba..e68633c7d 100644 --- a/logo/README.md +++ b/logo/README.md @@ -23,7 +23,7 @@ Rust Logo is licensed under CC-BY, which allows reuse and modifications for any ## 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: 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. diff --git a/units/README.md b/units/README.md index 4b419c4fc..177b82ff1 100644 --- a/units/README.md +++ b/units/README.md @@ -1,14 +1,11 @@ -Bitcoin Units -============= +# Bitcoin Units This crate provides basic Bitcoin numeric units such as `Amount`. - ## Minimum Supported Rust Version (MSRV) This library should always compile with any combination of features on **Rust 1.56.1**. - ## Licensing The code in this project is licensed under the [Creative Commons CC0 1.0 Universal license](LICENSE).