Crate kyoto

Kyoto is a conservative, private, and vetted Bitcoin client built in accordance with the BIP157 and BIP158 standards. Conservative, as in Kyoto makes very little assumptions about the underlying memory requirements of the device running the software. Private, as in the Bitcoin nodes that serve Kyoto nodes data do not know what transactions the client is querying for, only the entire Bitcoin block. Vetted, as in the dependencies of the core library are meant to remain limited, rigorously tested, and absolutely necessary.

Example usage

use std::str::FromStr;
use std::collections::HashSet;
use kyoto::{NodeBuilder, NodeMessage, 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 (sender, mut receiver) = client.split();
    // Sync with the single script added
    if let Ok(message) = receiver.recv().await {
        match message {
            NodeMessage::Dialog(d) => tracing::info!("{}", d),
            NodeMessage::Warning(e) => tracing::warn!("{}", e),
            NodeMessage::Synced(update) => {
                tracing::info!("Synced chain up to block {}", update.tip().height);
                tracing::info!("Chain tip: {}", update.tip().hash);
            }
            _ => (),
        }
    }
    sender.shutdown().await;
}

Getting started

The core module documentation is likely the best place to start when developing an application with Kyoto.

Features

dns: if no peers are provided, query DNS seeds for Bitcoin nodes to connect to. Default and recommend feature.

database: use the default rusqlite database implementations. Default and recommend feature.

filter-control: check filters and request blocks directly. Recommended for silent payments or strict chain ordering implementations.

tor No MSRV guarantees: connect to nodes over the Tor network.

Modules

• chain
  Strucutres and checkpoints related to the blockchain.
• core
  Tools to build and run a compact block filters node.
• db
  Traits and structures that define the data persistence required for a node.

Macros

• impl_sourceless_error
  Implement std::error::Error for an error with no sources.

Structs

• Address
  A Bitcoin address.
• Block
  Bitcoin block.
• BlockHash
  A bitcoin block hash.
• Client
  A Client allows for communication with a running node.
• ClientSender
  Send messages to a node that is running so the node may complete a task.
• DisconnectedHeader
  A block Header that was disconnected from the chain of most work along with its previous height.
• FailurePayload
  An attempt to broadcast a tranasction failed.
• Header
  Bitcoin block header.
• HeaderCheckpoint
  A known block hash in the chain of most work.
• IndexedBlock
  A Bitcoin Block with associated height.
• Node
  A compact block filter node. Nodes download Bitcoin block headers, block filters, and blocks to send relevant events to a client.
• NodeBuilder
  Build a Node in an additive way.
• Progress
  The progress of the node during the block filter download process.
• Receiver
  Receiving-half of the broadcast channel.
• ScriptBuf
  An owned, growable script.
• ServiceFlags
  Flags to indicate which network services a node supports.
• SqliteHeaderDb
  Header storage implementation with SQL Lite.
• SqlitePeerDb
  Structure to create a SQL Lite backend to store peers.
• StatelessPeerStore
  A simple peer store that does not save state in between sessions. If DNS is not enabled, a node will require at least one peer to connect to. Thereafter, the node will find peers to connect to throughout the session.
• SyncUpdate
  The node has synced to a new tip of the chain.
• Transaction
  Bitcoin transaction.
• TrustedPeer
  A peer on the Bitcoin P2P network
• TxBroadcast
  Broadcast a Transaction to a set of connected peers.
• Txid
  A bitcoin transaction hash/transaction ID.

Enums

• AddrV2
  Supported networks for use in BIP155 addrv2 message
• ClientError
  Errors occuring when the client is talking to the node.
• ConnectionType
  How to connect to peers on the peer-to-peer network
• Network
  The cryptocurrency network to act on.
• NodeError
  Errors that prevent the node from running.
• NodeMessage
  Messages receivable by a running node.
• NodeState
  The state of the node with respect to connected peers.
• RejectReason
  message rejection reason as a code
• TxBroadcastPolicy
  The strategy for how this transaction should be shared with the network.
• Warning
  Warnings a node may issue while running.

Constants

• MAINNET_HEADER_CP
  Known block hashes on the Bitcoin blockchain.
• SIGNET_HEADER_CP
  Known block hashes for Signet.
• TESTNET4_HEADER_CP
  Known block hashes for Testnet4.

Traits

• HeaderStore
  Methods required to persist the chain of block headers.
• PeerStore
  Methods that define a list of peers on the Bitcoin P2P network.