Crate electrum_streaming_client

Expand description

§electrum_streaming_client

A streaming, sans-IO Electrum client for asynchronous and blocking Rust applications.

This crate provides low-level primitives and high-level clients for communicating with Electrum servers over JSON-RPC. It supports both asynchronous (futures/tokio) and blocking transport models.

§Features

Streaming protocol support: Handles both server-initiated notifications and responses.
Transport agnostic: Works with any I/O type implementing the appropriate Read/Write traits.
Sans-IO core: The State struct tracks pending requests and processes server messages.
Typed request/response system: Strongly typed Electrum method wrappers with minimal overhead.

§Example (async with Tokio)

use electrum_streaming_client::{AsyncClient, AsyncBatchRequest, Event};
use tokio::net::TcpStream;
use futures::StreamExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let stream = TcpStream::connect("127.0.0.1:50001").await?;
    let (reader, writer) = stream.into_split();
    let (client, mut events, worker) = AsyncClient::new_tokio(reader, writer);

    tokio::spawn(worker); // spawn the client worker task

    let mut batch = AsyncBatchRequest::new();
    let fut = batch.request(electrum_streaming_client::request::RelayFee);
    client.send_batch(batch)?;
    let relay_fee = fut.await?;

    println!("Relay fee: {relay_fee:?}");

    while let Some(event) = events.next().await {
        println!("Event: {event:?}");
    }

    Ok(())
}

§Optional Features

tokio: Enables AsyncClient::new_tokio for use with Tokio-compatible streams.

§License

MIT

Re-exports§

pub use request::Request;

Modules§

io: Low-level I/O utilities for reading and writing Electrum JSON-RPC messages.
notification: Defines parsed Electrum server notifications.
request: Defines the request abstraction used to interact with the Electrum server.
response: Types representing structured responses returned by the Electrum server.

Structs§

AsyncBatchRequest: A builder for batching multiple asynchronous requests to the Electrum server.
AsyncClient: An asynchronous Electrum client built on the futures I/O ecosystem.
BlockingBatchRequest: A builder for batching multiple blocking requests to the Electrum server.
BlockingClient: A blocking Electrum client built on standard I/O.
ElectrumScriptHash: A script hash used by Electrum to identify wallet outputs.
ElectrumScriptStatus: Represents the Electrum server’s status hash for a specific script.
RawNotification: A raw server-initiated JSON-RPC notification.
RawRequest: A raw JSON-RPC request to be sent to the Electrum server.
RawResponse: A raw JSON-RPC response from the Electrum server.
ResponseError: Electrum server responds with an error.
State: A sans-io structure that manages the state of an Electrum client.
Version: Represents the jsonrpc version field in JSON-RPC messages.

Enums§

AsyncPendingRequest: An internal representation of a pending asynchronous Electrum request.
BatchRequestError: An error that can occur when adding a request to a batch or polling its result.
BlockingPendingRequest: An internal representation of a pending blocking Electrum request.
ErroredRequest: A request that received an error response from the Electrum server.
Event: Represents a high-level event produced after processing a server notification or response.
MaybeBatch: Represents either a single item or a batch of items.
ProcessError: An error that occurred while processing an incoming server response or notification.
RawNotificationOrResponse: A raw incoming message from the Electrum server.
SatisfiedRequest: A successfully handled request and its decoded server response.

Constants§

JSONRPC_VERSION_2_0: The JSON-RPC protocol version supported by this client.

Traits§

PendingRequest: A trait representing a request that has been sent to the Electrum server and is awaiting a response.

Type Aliases§

AsyncEventReceiver: The receiving half of the internal event stream, returned to users of AsyncClient.
AsyncEventSender: The sending half of the internal event stream, used to emit Events from the client worker loop.
AsyncPendingRequestTuple: A tracked or untracked asynchronous request, paired with an optional response sender.
AsyncRequestError: The error returned by AsyncClient::send_request when a request fails.
AsyncRequestReceiver: The receiving half of the request channel used internally by the async client.
AsyncRequestSendError: The error that occurs when a request cannot be sent into the async request channel.
AsyncRequestSender: The sending half of the channel used to enqueue one or more requests from AsyncClient.
AsyncResponseReceiver: A oneshot receiver used to await the result of a tracked async request.
AsyncResponseSender: A oneshot sender used to deliver the result of a tracked async request.
AsyncState: Internal State instance specialized for tracking asynchronous requests.
BlockingEventReceiver: Channel receiver used to receive Events from the Electrum server.
BlockingEventSender: Channel sender used by the read thread to emit Events.
BlockingPendingRequestTuple: A tracked or untracked blocking request, paired with an optional response sender.
BlockingRequestError: Error returned by BlockingClient::send_request if the request fails or is canceled.
BlockingRequestReceiver: Channel receiver used by the write thread to dequeue pending requests.
BlockingRequestSendError: Error that occurs when a blocking request cannot be sent to the internal request channel.
BlockingRequestSender: Channel sender for sending blocking requests from BlockingClient to the write thread.
BlockingResponseReceiver: One-shot receiver used to block and wait for a response to a tracked request.
BlockingResponseSender: One-shot sender used to deliver the result of a tracked blocking request.
BlockingState: Internal State specialized for tracking blocking requests.
CowStr: An owned or borrowed static string.
DoubleSHA: A double SHA256 hash (sha256d) used for Merkle branches and header proofs.
MethodAndParams: A method name and its corresponding parameters, as used in a JSON-RPC request.
ResponseResult: A server response that is either a success (Ok) or a JSON-RPC error (Err).

Crate electrum_streaming_clientCopy item path