Change library structure

-sys now only generates raw bindings

The top-level library exposes the safe rust wrappers

The example binary is moved to the example directory

Author: sedited

Cargo.toml

@@ -1,25 +1,29 @@
 [package]
-name = "rust-bitcoinkernel"
+name = "bitcoinkernel"
 version = "0.0.1"
 edition = "2021"
+authors = ["TheCharlatan <[email protected]>"]
+description = "Safe Rust bindings to libbitcoinkernel"
+license = "MIT"
+repository = "https://github.com/TheCharlatan/rust-bitcoinkernel"
+documentation = "https://docs.rs/bitcoinkernel"
+keywords = ["bitcoin", "ffi", "libbitcoinkernel"]
+categories = ["cryptography::cryptocurrencies"]
+readme = "README.md"
 
 [dependencies]
-silentpayments = "0.1"
-bitcoin = "0.31"
-secp256k1 = "0.28"
-env_logger = "0.11"
-log = "0.4"
 libbitcoinkernel-sys = { path = "libbitcoinkernel-sys" }
 
 [dev-dependencies]
 hex = "0.4"
 env_logger = "0.11"
 log = "0.4"
-libbitcoinkernel-sys = { path = "libbitcoinkernel-sys" }
+bitcoin = "0.31"
 tempdir = "0.3"
 
 [workspace]
 members = [
-    "libbitcoinkernel-sys",
-    "fuzz"
+    "examples",
+    "fuzz",
+    "libbitcoinkernel-sys"
 ]

README.md

@@ -4,7 +4,8 @@
 
 `rust-bitcoinkernel` is a wrapper around
 [libbitcoinkernel](https://github.com/bitcoin/bitcoin/issues/24303), a C++
-library exposing Bitcoin Core's validation engine.
+library exposing Bitcoin Core's validation engine. It supports both validation
+of blocks and transaction outputs as well as reading block data.
 
 ## Building
 
@@ -29,14 +30,11 @@ dependencies. Once setup, run:
 cargo b
 ```
 
-And for the example binary (takes the path to a previously used Bitcoin Core
-regtest directory):
+## Examples
 
-```bash
-cargo run -- /path/to/.bitcoin/regtest
-```
-
-The example binary implements a silent payments scanner.
+Examples for the usage of the library can be found in the `examples/` directory
+and the `tests`. For now, the example binary implements a bare-bones silent
+payments scanner.
 
 ## Fuzzing
 

examples/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "examples"
+edition = "2021"
+publish = false
+
+[[bin]]
+name = "silentpaymentscanner"
+path = "src/silentpaymentscanner.rs"
+
+[dependencies]
+silentpayments = "0.1"
+bitcoin = "0.31"
+secp256k1 = "0.28"
+env_logger = "0.11"
+log = "0.4"
+bitcoinkernel = { path = ".." }

examples/README.md

@@ -0,0 +1,6 @@
+# Example
+
+The example binary implements a silent payments scanner. To run it:
+
+cargo run -- /path/to/.bitcoin/regtest
+

src/main.rs renamed to examples/src/silentpaymentscanner.rs

@@ -5,12 +5,12 @@ use std::process;
 use bitcoin::consensus::deserialize;
 use bitcoin::hashes::Hash;
 use bitcoin::{PrivateKey, XOnlyPublicKey};
-use env_logger::Builder;
-use libbitcoinkernel_sys::{
+use bitcoinkernel::{
     BlockManagerOptions, ChainType, ChainstateLoadOptions, ChainstateManager,
     ChainstateManagerOptions, Context, ContextBuilder, KernelError,
     KernelNotificationInterfaceCallbackHolder, Log, Logger,
 };
+use env_logger::Builder;
 use log::LevelFilter;
 use secp256k1::{PublicKey, Secp256k1, SecretKey};
 use silentpayments::receiving::{Label, Receiver};

fuzz/Cargo.toml

@@ -11,8 +11,8 @@ cargo-fuzz = true
 libfuzzer-sys = "0.4"
 arbitrary = { version = "1.1", features = ["derive"] }
 
-[dependencies.libbitcoinkernel-sys]
-path = "../libbitcoinkernel-sys"
+[dependencies.bitcoinkernel]
+path = ".."
 
 [[bin]]
 name = "fuzz_target_chainman"

fuzz/fuzz_targets/fuzz_target_block.rs

@@ -1,6 +1,6 @@
 #![no_main]
 
-use libbitcoinkernel_sys::Block;
+use bitcoinkernel::Block;
 use libfuzzer_sys::fuzz_target;
 
 fuzz_target!(|data: &[u8]| {

fuzz/fuzz_targets/fuzz_target_chainman.rs

@@ -6,9 +6,9 @@ use libfuzzer_sys::fuzz_target;
 
 use arbitrary::Arbitrary;
 
-use libbitcoinkernel_sys::{
+use bitcoinkernel::{
     disable_logging, Block, BlockManagerOptions, ChainType, ChainstateLoadOptions,
-    ChainstateManager, ChainstateManagerOptions, Context, ContextBuilder,
+    ChainstateManager, ChainstateManagerOptions, Context, ContextBuilder, KernelError,
     KernelNotificationInterfaceCallbackHolder,
 };
 
@@ -78,7 +78,7 @@ fuzz_target!(|data: ChainstateManagerInput| {
     let blocks_dir = format!("{}/blocks", data_dir);
     let chainman_opts = match ChainstateManagerOptions::new(&context, &data_dir) {
         Ok(opts) => opts,
-        Err(libbitcoinkernel_sys::KernelError::CStringCreationFailed(_)) => return,
+        Err(KernelError::CStringCreationFailed(_)) => return,
         Err(err) => panic!("this should never happen: {}", err),
     };
     let blockman_opts = BlockManagerOptions::new(&context, &blocks_dir).unwrap();
@@ -91,7 +91,7 @@ fuzz_target!(|data: ChainstateManagerInput| {
             .set_block_tree_db_in_memory(data.block_tree_db_in_memory)
             .set_chainstate_db_in_memory(data.chainstate_db_in_memory),
     ) {
-        Err(libbitcoinkernel_sys::KernelError::Internal(_)) => {
+        Err(KernelError::Internal(_)) => {
             return;
         }
         Err(err) => {

fuzz/fuzz_targets/fuzz_target_verify.rs

@@ -3,7 +3,7 @@
 use arbitrary::Arbitrary;
 use libfuzzer_sys::fuzz_target;
 
-use libbitcoinkernel_sys::{verify, ScriptPubkey, Transaction, TxOut};
+use bitcoinkernel::{verify, ScriptPubkey, Transaction, TxOut};
 
 #[derive(Debug, Arbitrary)]
 pub struct UtxoWrapper {

libbitcoinkernel-sys/Cargo.toml

@@ -2,6 +2,10 @@
 name = "libbitcoinkernel-sys"
 version = "0.0.1"
 edition = "2021"
+authors = ["TheCharlatan <[email protected]>"]
+description = "Raw Rust bindings to libbitcoinkernel"
+license = "MIT"
+repository = "https://github.com/TheCharlatan/rust-bitcoinkernel"
 links = "libbitcoinkernel"
 build = "build.rs"