Bitcoin Core REST API 的 Rust REST 客户端

一个用于调用 Bitcoin Core REST API 的 Rust REST 客户端库。它使得与 Bitcoin Core REST 接口通信变得简单。

REST 接口对于快速迭代区块链非常有用，因为它可以请求以二进制形式的数据块和交易，而不需要将数据序列化/反序列化为 JSON。它是不需要认证的，因此无需担心存储凭据。

它还提供了快速检索大量区块头部和 BIP157 压缩区块过滤头部 API。它还支持获取区块链信息、内存池信息、原始内存池、查询 UTXO 集合以及软分叉部署状态。

更多信息请参阅 https://github.com/bitcoin/bitcoin/blob/master/doc/REST-interface.md。

安装

在您的项目目录中运行以下 Cargo 命令

cargo add bitcoincore-rest

或者将以下行添加到您的 Cargo.toml 文件中

bitcoincore-rest = "4.0.2"

使用方法

Bitcoin Core 的 bitcoind 实例必须在命令行上通过 -rest 或在 bitcoin.conf 文件中通过 rest=1 来启动。

use bitcoincore_rest::prelude::*;

async fn get_block(height: u64) -> Result<Block, Error> {
    let rest = RestClient::network_default(Network::Bitcoin);
    rest.get_block_at_height(height).await
}

API

遗憾的是，在 docsrs 中 async_trait 特性函数被展开，因此这里提供了 RestApi 的未展开函数，该函数由 RestClient 实现

async fn get_block_headers(
    &self,
    start_hash: BlockHash,
    count: u32,
) -> Result<Vec<Header>, Error>;

async fn get_block_at_height(&self, height: u64) -> Result<Block, Error>;

async fn get_block_hash(&self, height: u64) -> Result<BlockHash, Error>;

async fn get_block(&self, hash: BlockHash) -> Result<Block, Error>;

async fn get_transaction(&self, txid: Txid) -> Result<Transaction, Error>;

async fn get_block_filter_headers(
    &self,
    start_hash: BlockHash,
    count: u32,
) -> Result<Vec<FilterHeader>, Error>;

async fn get_block_filter(&self, hash: BlockHash) -> Result<BlockFilter, Error>;

async fn get_chain_info(&self) -> Result<GetBlockchainInfoResult, Error>;

async fn get_utxos(
    &self,
    outpoints: &[OutPoint],
    check_mempool: bool,
) -> Result<GetUtxosResult, Error>;

async fn get_mempool_info(&self) -> Result<GetMempoolInfoResult, Error>;

async fn get_mempool(&self) -> Result<HashMap<Txid, GetMempoolEntryResult>, Error>;

async fn get_mempool_txids(&self) -> Result<Vec<Txid>, Error>;

async fn get_mempool_txids_and_sequence(
    &self,
) -> Result<GetMempoolTxidsAndSequenceResult, Error>;

async fn get_deployment_info(&self) -> Result<GetDeploymentInfoResult, Error>;

/// Only available on Bitcoin Core v25.1 and later
///
/// WARNING: CALLING THIS CONNECTED TO BITCOIN CORE V25.0 WILL CRASH BITCOIND
///
/// IT IS MARKED UNSAFE TO ENSURE YOU ARE NOT USING BITCOIN CORE V25.0
async unsafe fn get_deployment_info_at_block(
    &self,
    hash: BlockHash,
) -> Result<GetDeploymentInfoResult, Error>;

特性

默认情况下，此库包含一个名为 RestClient 的结构体，该结构体通过使用 reqwest 库实现了 RestApi。若要避免将 reqwest 作为依赖项，并实现自己的 RestApi 版本，请在您的 Cargo.toml 中设置 default-features = false

bitcoincore-rest = { version = "4.0.2", default-features = false }

您需要在 RestApi 上实现 get_json 和 get_bin 方法，使用您自己的 http 功能。所有方法都是 GET 请求。例如，使用 surf http 库和 thiserror

use bitcoincore_rest::{
    async_trait::async_trait, bytes::Bytes, serde::Deserialize, Error, RestApi,
};

#[derive(thiserror::Error, Debug)]
pub enum SurfError {
    #[error("surf error")]
    Surf(surf::Error),
}

struct NewClient;

#[async_trait]
impl RestApi for NewClient {
    async fn get_json<T: for<'a> Deserialize<'a>>(&self, path: &str) -> Result<T, Error> {
        surf::get(format!("https://127.0.0.1:8332/{path}"))
            .recv_json()
            .await
            .map_err(|e| Error::CustomError(Box::new(SurfError::Surf(e))))
    }

    async fn get_bin(&self, path: &str) -> Result<Bytes, Error> {
        surf::get(format!("https://127.0.0.1:8332/{path}"))
            .recv_bytes()
            .await
            .map_err(|e| Error::CustomError(Box::new(SurfError::Surf(e))))
            .map(Bytes::from)
    }
}