Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rustaceanrob/kyoto
An implementation of Bitcoin Improvement Proposal 157/158
https://github.com/rustaceanrob/kyoto
bitcoin cryptocurrency networking peer-to-peer
Last synced: 4 days ago
JSON representation
An implementation of Bitcoin Improvement Proposal 157/158
- Host: GitHub
- URL: https://github.com/rustaceanrob/kyoto
- Owner: rustaceanrob
- License: other
- Created: 2024-05-03T06:27:54.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-01-25T21:08:45.000Z (13 days ago)
- Last Synced: 2025-01-27T14:26:34.304Z (11 days ago)
- Topics: bitcoin, cryptocurrency, networking, peer-to-peer
- Language: Rust
- Homepage: https://docs.rs/kyoto-cbf
- Size: 1.16 MB
- Stars: 55
- Watchers: 8
- Forks: 8
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Kyoto: Bitcoin Light Client
An Implementation of BIP-157/BIP-158
## 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::str::FromStr;
use std::collections::HashSet;
use kyoto::{NodeBuilder, Log, Event, Client, Address, Network, HeaderCheckpoint, BlockHash};
#[tokio::main]
async fn main() {
// Add third-party logging
let subscriber = tracing_subscriber::FmtSubscriber::new();
tracing::subscriber::set_global_default(subscriber).unwrap();
// Add Bitcoin scripts to scan the blockchain for
let address = Address::from_str("tb1q9pvjqz5u5sdgpatg3wn0ce438u5cyv85lly0pc")
.unwrap()
.require_network(Network::Signet)
.unwrap()
.into();
let mut addresses = HashSet::new();
addresses.insert(address);
// Start the scan after a specified header
let checkpoint = HeaderCheckpoint::closest_checkpoint_below_height(170_000, Network::Signet);
// Create a new node builder
let builder = NodeBuilder::new(Network::Signet);
// Add node preferences and build the node/client
let (mut node, client) = builder
// The Bitcoin scripts to monitor
.add_scripts(addresses)
// Only scan blocks strictly after an anchor checkpoint
.anchor_checkpoint(checkpoint)
// The number of connections we would like to maintain
.num_required_peers(2)
.build_node()
.unwrap();
// Run the node and wait for the sync message;
tokio::task::spawn(async move { node.run().await });
// Split the client into components that send messages and listen to messages
let Client { requester, mut log_rx, mut event_rx } = client;
// Sync with the single script added
loop {
tokio::select! {
log = log_rx.recv() => {
if let Some(log) = log {
match log {
Log::Dialog(d) => tracing::info!("{d}"),
_ => (),
}
}
}
event = event_rx.recv() => {
if let Some(event) = event {
match event {
Event::Synced(_) => {
tracing::info!("Sync complete!");
break;
},
_ => (),
}
}
}
}
}
requester.shutdown().await;
```
## Minimum Supported Rust Version (MSRV) Policy
The `kyoto` core library with default features supports an MSRV of Rust 1.63.
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 )
* MIT license ([LICENSE-MIT](LICENSE-MIT) or )
at your option.