## About
Kyoto is aiming to be a simple, memory-conservative, and private Bitcoin client for developers to build wallet applications. To read more about the scope, usage recommendations, and implementation details, see [DETAILS.md](./doc/DETAILS.md).
## Running an example
To run the Signet example, in the root directory:
```
cargo run --example signet
```
Or, with `just`:
```
just example
```
## Getting Started
The following snippet demonstrates how to build a Kyoto node. See the [docs](https://docs.rs/kyoto-cbf) for more details on the `NodeBuilder`, `Node`, `Client`, and more.
```rust
use std::collections::HashSet;
use kyoto::{NodeBuilder, NodeMessage, Address, Network, HeaderCheckpoint, BlockHash, TrustedPeer};
let address = Address::from_str("tb1q9pvjqz5u5sdgpatg3wn0ce438u5cyv85lly0pc")
.unwrap()
.require_network(Network::Signet)
.unwrap()
.into();
let mut addresses = HashSet::new();
addresses.insert(address);
let builder = NodeBuilder::new(bitcoin::Network::Signet);
// Add node preferences and build the node/client
let (node, client) = builder
// Add the peers
.add_peers(vec![TrustedPeer::from_ip(peer_1), TrustedPeer::from_ip(peer_1)])
// The Bitcoin scripts to monitor
.add_scripts(addresses)
// Only scan blocks strictly after an anchor checkpoint
.anchor_checkpoint(HeaderCheckpoint::new(
180_000,
BlockHash::from_str("0000000870f15246ba23c16e370a7ffb1fc8a3dcf8cb4492882ed4b0e3d4cd26")
.unwrap(),
))
// The number of connections we would like to maintain
.num_required_peers(2)
// Create the node and client
.build_node()
.unwrap();
```
## Minimum Supported Rust Version (MSRV) Policy
The `kyoto` core library with default features supports an MSRV of Rust 1.63. To build the library with Rust 1.63, the `database` feature requires a pinned dependency: `cargo update -p allocator-api2 --precise "0.2.9"`.
While connections over the Tor protocol are supported by the feature `tor`, the dependencies required cannot support the MSRV. As such, no MSRV guarantees will be made when using Tor, and the feature should be considered experimental.
## Integration Testing
The preferred workflow is by using `just`. If you do not have `just` installed, check out the [installation page](https://just.systems/man/en/chapter_4.html).
To run the unit tests and doc tests:
```
just test
```
To sync with a live Signet node:
```
just sync
```
And to run scenarios against your `bitcoind` instance, set a `BITCOIND_EXE` environment variable to the path to `bitcoind`:
```
export BITCOIND_EXE = "/usr/path/to/bitcoind/"
```
You may want to add this to your bash or zsh profile.
To run the `bitcoind` tests:
```
just integrate
```
If you do not have `bitcoind` installed, you may simply run `just integrate` and it will be installed for you in the `build` folder.
## Project Layout
`chain`: Contains all logic for syncing block headers, filter headers, filters, parsing blocks. Also contains preset checkpoints for Signet, Regtest, and Bitcoin networks. Notable files: `chain.rs`
`core`: Organizes the primary user-facing components of the API. This includes both the `Node` and the `Client` that all developers will interact with, as well as the `NodeBuilder`. Importantly includes `peer_map.rs`, which is the primary file that handles peer threads by sending messages, persisting new peers, banning peers, and managing peer task handles. `node.rs` is the main application loop, responsible for driving the node actions. Notable files: `node.rs`, `peer_map.rs`, `builder.rs`, `client.rs`
`db`: Defines how data must be persisted with `traits.rs`, and includes some opinionated defaults for database components.
`filters`: Additional structures for managing compact filter headers and filters, used by `chain.rs`
`network`: Opens and closes connections, handles encryption and decryption of messages, generates messages, parses messages, times message response times, performs DNS lookups. Notable files: `peer.rs`, `reader.rs`, `parsers.rs`, `outbound_messages.rs`
## Contributing
Please read [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
## License
Licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or 
