5 releases (breaking)
new 0.5.0 | Nov 7, 2024 |
---|---|
0.4.0 | Oct 28, 2024 |
0.3.0 | Oct 1, 2024 |
0.2.0 | Sep 23, 2024 |
0.1.0 | Aug 26, 2024 |
#127 in #bitcoin
334 downloads per month
Used in bdk_kyoto
400KB
9K
SLoC
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.
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 for more details on the NodeBuilder
, Node
, Client
, and more.
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 (mut node, mut 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.
To run the unit tests:
just test
To sync with a live Signet node:
just sync
And to run scenarios against your bitcoind
instance:
just integrate
The default path to the .bitcoin
directory is for Linux. To set this path to another operating system or location:
just bitcoindir=/path/to/bitcoin/folder/ integrate
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 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 or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Dependencies
~11–31MB
~447K SLoC