3 releases (1 stable)
2.20.1-0.5.0 | Aug 12, 2022 |
---|---|
2.19.1 | Jul 5, 2020 |
2.19.1-3 | Feb 24, 2022 |
#4 in #groestlcoin
24 downloads per month
Used in groestlcoin
3MB
55K
SLoC
Contains (obscure autoconf code, 61KB) depend/groestlcoin/configure.ac, (obscure autoconf code, 17KB) configure.ac
Groestlcoin's libgroestlcoinconsensus
with Rust bindings
This project builds the libgroestlcoinconsensus
library from Groestlcoin's C++ sources using cargo and provides Rust bindings to its API.
libgroestlcoinconsensus
allows transaction verification using Groestlcoin's unique script engine.
Groestlcoin enabled applications SHOULD use the libgroestlcoinconsensus
library to avoid accepting transactions that the Groestlcoin network nodes would not accept.
This project simplifies a Rust developer's life by creating the libgroestlcoinconsensus
library with cargo.
No need to deal with the archaic C++ toolchain directly.
This also simplifies cross-compiling the consensus library e.g., for a mobile application.
libgroestlcoinconsensus
refers to code from another library secp256k1.
A snapshot of that library is also included in the Groestlcoin sources, therefore it could be baked into libgroestlcoinconsensus
.
A typical Groestlcoin enabled application will however want to access further secp256k1 functions.
The project rust-secp256k1 offers a cargo build and Rust bindings, therefore we depend on that instead of compiling the Groestlcoin embedded sources into libgroestlcoinconsensus
q.
This introduces a risk, since a difference between the two secp256k1 sources could break consensus with Groestlcoin.
Version numbers
We use [slightly abuse] semantic versioning. The first Major.Minor.Patch
number tracks the vendored Groestlcoin Core code (see below), the second Major.Minor.Patch
tracks this crate.
For example, if we upgrade the Groestlcoin Core code by a Patch
version we also bump our Patch
version.
One side effect of this is that crates.io
shows our release versions in yellow as if they were pre-release versions, this is due to us using a -
which, in semantic versioning, implies a pre-release version.
Groestlcoin Core subtree
We use a git subtree to vendor the Groestlcoin Core code. This can be seen from the following commits that were created using git subtree add --prefix='depend/groestlcoin' https://github.com/groestlcoin/groestlcoin.git v2.19.1 --squash
.
0c8f8595b Squashed 'depend/groestlcoin/' content from commit 9b4017c7c
b96a589b0 Merge commit '0c8f8595b64fa28c5aedfa37d28ecda7e36e1dc5' as 'depend/groestlcoin'
To use a later version of Groestlcoin Core, for example, v2.20.1
git subtree pull --prefix='depend/groestlcoin' https://github.com/groestlcoin/groestlcoin.git v2.20.1 --squash
MSRV
The MSRV of this crate is 1.41.1.
Githooks
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:
git config --local core.hooksPath githooks/
Alternatively add symlinks in your .git/hooks
directory to any of the githooks we provide.
API
The API is very basic, exposing Groestlcoin's API as is. This is intentional to keep this project to a minimal footprint and add no further runtime dependencies. You will need another Rust library to serialize Groestlcoin transactions and scripts.
Verify a single spend (input) of a Groestlcoin transaction:
verify (spent_output_script: &[u8], amount: u64, spending_transaction: &[u8], input_index: usize) -> Result<(), Error>
Arguments
- spend_output_script: a Groestlcoin transaction output script to be spent
- amount: The spent output amount in gros
- spending_transaction: spending Groestlcoin transaction, serialized in Groestlcoin's on wire format
- input_index: index of the input within spending_transaction
Note that spent amount will only be checked for Segwit transactions. The above example is not segwit therefore verify will succeed with any amount.