chore: format and standardize all markdowns files

according to the github flavor
(https://github.github.com/gfm/)
This commit is contained in:
Jose Storopoli 2024-04-27 06:29:23 -03:00
parent c4d017e7c4
commit b355740da4
No known key found for this signature in database
GPG Key ID: 29E00111DE172C28
10 changed files with 55 additions and 45 deletions

View File

@ -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).

View File

@ -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.

View File

@ -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.

View File

@ -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`.

View File

@ -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/
``` ```

View File

@ -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
```

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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).