Groestlcoin slices
ZERO allocations parse library for Groestlcoin data structures such as [bsl::Transaction
]s, [bsl::Block
]s
and others available in the [bsl
] module.
Data is accessed by providing [Visitor
] structs for the data the user is interested in.
// Calculate the amount of outputs in mainnet block 702861 in satoshi
use ;
;
let mut sum = Sum;
let block_bytes: & = mainnet_702861;
let block = visit.unwrap;
assert_eq!
Data structures are read-only and parsed data must be in memory, no streaming API.
Tradeoffs
Check the CONS before using this library, use rust-groestlcoin if they are too restrictive for your case.
Pros
- Deserialization is amazingly fast, since no allocation is made during parsing.
- Serialization is instant, since a slice of the serialized data is kept in the structure.
- [
bsl
] types are suitable for db key and values, in fact there is a specificredb
feature - hashing a little faster because slice are ready without the need of re-serializing data.
- No mandatory dependency.
- No standard.
- Calculate txid and block hash via optional dep
groestlcoin_hashes
orsha2
. - Visitor pattern to visit just what you are interested in.
Cons
- Full data must be in memory, there is no streaming (Read/Write) API.
- Data structure are read-only, cannot be modified.
- Visitor pattern requires user-built data structure for visiting.
Features
Hashing
Use feature sha2
or groestlcoin_hashes
to calculate hashes of blocks and transactions.
The former is faster, the latter is more likely to be in your tree if you work with rust-groestlcoin
ecosystem's crates.
redb
With the redb
feature activated some type allows to be used as value and key in the
redb database. groestlcoin slices types are well suited to be used
as key and values in the database because conversion from/to slices is immediate.
rust-groestlcoin
With the feature groestlcoin
activated some types allows to be converted in the rust-groestlcoin
counterpart: for example bsl::TxOut
could be converted in groestlcoin::TxOut
.
You may think if you need groestlcoin::TxOut
you can decode the bytes directly into it without
using this library, and it is mostly true, but sometimes it may be convenient to use both types, for
example using groestlcoin slices with datatabases, but you may need to access fields more conveniently
than writing a visitor for it and thus convert to rust-groestlcoin types.
Moreover, conversions may leverage type invariants and be faster than starting from a generic byte stream.
Test
Bench
RUSTFLAGS='--cfg=bench'
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
)
- benches ending with
_groestlcoin
userust-groestlcoin
- benches ending with
_sha2
usesha2
lib instead ofgroestlcoin_hashes
Comparison against rust-groestlcoin
block_deserialize
is almost 10 times faster then block_deserialize_groestlcoin
. It may see unfair
comparison since you can't for example iterate transactions from the resulted object in case of
block_deserialize
, but looking at the sum_outputs
example where a visitor is used to access
every outputs in a block we se there isn't noticeable difference.
Hashing
block_hash
and block_hash_groestlcoin
use the same code to hash, however groestlcoin_slice is about 7%
faster because use a slice already available instead of serializing back data.
Similar results apply between txid
and txid_groestlcoin
.
The performance increase is more notable (30%) between hash_block_txs
and hash_block_txs_groestlcoin
.
*_sha2
are not really representative on virtual CI machines since they are not hardware-accellerated.
Fuzz
Use cargo fuzz Run fuzzing with transaction as target.
Other target available in fuzz/fuzz_targets
Minimize corpus:
Doc
To build docs:
RUSTDOCFLAGS="--cfg docsrs"
MSRV
Minimum Supported Rust Version of this crate is 1.60.0 without redb
,slice_cache
features, (double check with what is running in the CI)
With slice_cache
feature MSRV is 1.64.0.
With redb
feature MSRV is 1.66.0.