Merge bitcoindevkit/rust-electrum-client#195: feat(ci): add justfile

df6675dc09 fix(docs): fix `bitcoin::block::Header` link (Luis Schwab)
4b98565ee2 feat(ci): add justfile (Luis Schwab)

Pull request description:

  This PR adds a `justfile` stolen from `rust-esplora-client`.

ACKs for top commit:
  oleonardolima:
    tACK df6675dc09

Tree-SHA512: 8d8f43c27631d7dc1c0eac28e01828510118a0600c762e9459b779a6423ceb6b1e3000f5c797d065a2ef6e511e2c47f6ad7bcf0182a515e573fc097e74f9e04b

.github/workflows/cont_integration.yml

@@ -0,0 +1,71 @@
+on: [push, pull_request]
+
+name: CI
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    env:
+      TEST_ELECTRUM_SERVER: electrum.blockstream.info:50001
+    strategy:
+      matrix:
+        rust:
+          - stable # STABLE
+          - 1.75.0 # MSRV
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ github.job }}-${{ hashFiles('**/Cargo.toml','**/Cargo.lock') }}
+      - name: Install rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ matrix.rust }}
+      - name: Test
+        run: cargo test --verbose --all-features
+      - name: Setup iptables for the timeout test
+        run: sudo ip6tables -I INPUT 1 -p tcp -d ::1 --dport 60000 -j DROP
+      - name: Timeout test
+        run: cargo test -- --ignored test_local_timeout
+      - run: cargo check --verbose --features=use-openssl
+      - run: cargo check --verbose --no-default-features --features=proxy
+      - run: cargo check --verbose --no-default-features --features=minimal
+      - run: cargo check --verbose --no-default-features --features=minimal,debug-calls
+      - run: cargo check --verbose --no-default-features --features=proxy,use-openssl
+      - run: cargo check --verbose --no-default-features --features=proxy,use-rustls
+      - run: cargo check --verbose --no-default-features --features=proxy,use-rustls-ring
+      - run: cargo check --verbose --no-default-features --features=proxy,use-rustls,use-rustls-ring
+
+  fmt:
+    name: Rust fmt
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          components: rustfmt
+      - name: Check fmt
+        run: cargo fmt --all -- --config format_code_in_doc_comments=true --check
+
+  clippy_check:
+    name: Rust clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@v1
+        with:
+          toolchain: 1.90.0
+          components: clippy
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@v2.2.1
+      - run: cargo clippy --all-features --all-targets -- -D warnings

.travis.yml

@@ -1,26 +0,0 @@
-language: rust
-rust:
-  - stable
-#  - 1.31.0 TODO: support the first 2018-edition toolchain
-env:
-    - TEST_ELECTRUM_SERVER=electrum.blockstream.info:50001
-    - TEST_ELECTRUM_SERVER=bitcoin.aranguren.org:50001
-before_script:
-  - rustup component add rustfmt
-# Run tests and check a few combinations of features
-script:
-  - cargo fmt -- --check --verbose
-  - cargo test --verbose --all
-  - cargo check --verbose --features=use-openssl
-  - cargo check --verbose --no-default-features --features=proxy
-  - cargo check --verbose --no-default-features --features=minimal
-  - cargo check --verbose --no-default-features --features=minimal,debug-calls
-  - cargo check --verbose --no-default-features --features=proxy,use-openssl
-  - cargo check --verbose --no-default-features --features=proxy,use-rustls
-
-before_cache:
-  - rm -rf "$TRAVIS_HOME/.cargo/registry/src"
-cache: cargo
-
-notifications:
-  email: false

CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project can be found here and in each release's git tag and can be viewed with `git tag -ln100 "v*"`.
+
+Contributors do not need to change this file but do need to add changelog details in their PR descriptions. The person making the next release will collect changelog details from included PRs and edit this file prior to each release.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.24.1]
+ - Default to `ring` if multiple `rustls` features are set #183
+
+## [0.24.0]
+ - Use default `CryptoProvider` if available, otherwise install `rustls`'s `CryptoProvider` based on features #171
+ - Add a new batch method for `blockchain.transaction.get_merkle` #170
+
+## [0.23.1]
+ - Fix batch request to Electrum servers out of order responses #160
+ - Allow types that references to `ElectrumApi` to also implement it #163
+
+## [0.23.0]
+
+ - Raise MSRV to `1.75` and bump `rustls` to `0.23.21` #159
+ - Enforce min `rustls` version 0.23.19 to support MSRV with fix for RUSTSEC-2024-0399 #158
+
+## [0.22.0]
+
+ - Updates the NoCertificateVerification implementation for the rustls::client::danger::ServerCertVerifier to use the rustls::SignatureScheme from CryptoProvider in use #150
+ - Add `id_from_pos` support #155
+
+## [0.21.0]
+
+ - Add use-rustls-ring feature #135
+ - refactor: make validate_merkle_proof more efficient #134
+ - chore: set rust edition to 2021, fix clippy, add ci fmt and clippy checks #139
+
+## [0.20.0]
+
+- Upgrade rustls to 0.23 #132
+- chore(deps): upgrade rust-bitcoin to 0.32.0 #133
+- ci: add test with MSRV 1.63.0 #128
+
+## [0.19.0]
+
+ - Add Batch::raw and improve docs #94
+ - Remove webpki and bump webpki-roots to v0.25 #117
+ - Upgrade rust-bitcoin to v0.31.0 #121
+ - Add utility to validate GetMerkleRes #122
+ - Enforce timeout on initial socks5 proxy connection #125
+
+## [0.18.0]
+
+ - Revert "errors if expecting headers notification but not subscribed" #115
+
+[0.18.0]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.17.0...0.18.0
+[0.19.0]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.18.0...0.19.0
+[0.20.0]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.19.0...0.20.0
+[0.21.0]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.20.0...0.21.0
+[0.22.0]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.21.0...0.22.0
+[0.23.0]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.22.0...0.23.0
+[0.23.1]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.23.0...0.23.1
+[0.24.0]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.23.1...0.24.0
+[0.24.1]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.24.0...0.24.1
+[Unreleased]: https://github.com/bitcoindevkit/rust-electrum-client/compare/0.24.1...HEAD

Cargo.toml

@@ -1,14 +1,16 @@
 [package]
 name = "electrum-client"
-version = "0.2.0-beta.1"
+version = "0.24.1"
 authors = ["Alekos Filini <alekos.filini@gmail.com>"]
 license = "MIT"
-homepage = "https://github.com/MagicalBitcoin/rust-electrum-client"
+homepage = "https://github.com/bitcoindevkit/rust-electrum-client"
-repository = "https://github.com/MagicalBitcoin/rust-electrum-client"
+repository = "https://github.com/bitcoindevkit/rust-electrum-client"
 documentation = "https://docs.rs/electrum-client/"
 description = "Bitcoin Electrum client library. Supports plaintext, TLS and Onion servers."
 keywords = ["bitcoin", "electrum"]
 readme = "README.md"
+rust-version = "1.75.0"
+edition = "2021"
 
 # loosely based on https://github.com/evgeniy-scherbina/rust-electrumx-client
 
@@ -18,21 +20,28 @@ path = "src/lib.rs"
 
 [dependencies]
 log = "^0.4"
-bitcoin = { version = "0.23", features = ["use-serde"] }
+bitcoin = { version = "0.32", features = ["serde"] }
 serde = { version = "^1.0", features = ["derive"] }
 serde_json = { version = "^1.0" }
 
 # Optional dependencies
-socks = { version = "^0.3", optional = true }
+openssl = { version = "0.10", optional = true }
-openssl = { version = "^0.10", optional = true }
+rustls = { version = "0.23.21", optional = true, default-features = false }
-rustls = { version = "0.16.0", optional = true, features = ["dangerous_configuration"] }
+webpki-roots = { version = "0.25", optional = true }
-webpki = { version = "0.21.0", optional = true }
+
-webpki-roots = { version = "^0.19", optional = true }
+byteorder = { version = "1.0", optional = true }
+
+[target.'cfg(unix)'.dependencies]
+libc = { version = "0.2", optional = true }
+
+[target.'cfg(windows)'.dependencies]
+winapi = { version="0.3.9", features=["winsock2"], optional = true }
 
 [features]
-default = ["socks", "webpki", "webpki-roots", "rustls"]
+default = ["proxy", "use-rustls"]
 minimal = []
 debug-calls = []
-proxy = ["socks"]
+proxy = ["byteorder", "winapi", "libc"]
-use-rustls = ["webpki", "webpki-roots", "rustls"]
+use-rustls = ["webpki-roots", "rustls/default"]
+use-rustls-ring = ["webpki-roots", "rustls/ring", "rustls/logging", "rustls/std", "rustls/tls12"]
 use-openssl = ["openssl"]

README.md

@@ -1,9 +1,15 @@
-# rust-electrum-client [![Build Status]][travis] [![Latest Version]][crates.io]
+# rust-electrum-client 
+[![Build Status]][GitHub Workflow] [![Latest Version]][crates.io] [![MSRV Badge]][Rust Blog]
 
-[Build Status]: https://api.travis-ci.org/MagicalBitcoin/rust-electrum-client.svg?branch=master
+[Build Status]: https://github.com/bitcoindevkit/rust-electrum-client/actions/workflows/cont_integration.yml/badge.svg
-[travis]: https://travis-ci.org/MagicalBitcoin/rust-electrum-client
+[GitHub Workflow]: https://github.com/bitcoindevkit/rust-electrum-client/actions?query=workflow%3ACI
 [Latest Version]: https://img.shields.io/crates/v/electrum-client.svg
 [crates.io]: https://crates.io/crates/electrum-client
-
+[MSRV Badge]: https://img.shields.io/badge/rustc-1.75.0%2B-lightgrey.svg
+[Rust Blog]: https://blog.rust-lang.org/2023/12/28/Rust-1.75.0.html
 
 Bitcoin Electrum client library. Supports plaintext, TLS and Onion servers.
+
+## Minimum Supported Rust Version (MSRV)
+
+This library should compile with any combination of features with Rust 1.75.0.

clippy.toml

@@ -0,0 +1 @@
+msrv="1.75.0"

examples/plaintext.rs

@@ -3,7 +3,7 @@ extern crate electrum_client;
 use electrum_client::{Client, ElectrumApi};
 
 fn main() {
-    let client = Client::new("tcp://electrum.blockstream.info:50001", None).unwrap();
+    let client = Client::new("tcp://electrum.blockstream.info:50001").unwrap();
     let res = client.server_features();
     println!("{:#?}", res);
 }

examples/ssl.rs

@@ -3,7 +3,7 @@ extern crate electrum_client;
 use electrum_client::{Client, ElectrumApi};
 
 fn main() {
-    let client = Client::new("ssl://electrum.blockstream.info:50002", None).unwrap();
+    let client = Client::new("ssl://electrum.blockstream.info:50002").unwrap();
     let res = client.server_features();
     println!("{:#?}", res);
 }

examples/tor.rs

@@ -1,19 +1,21 @@
 extern crate electrum_client;
 
-use electrum_client::{Client, ElectrumApi};
+use electrum_client::{Client, ConfigBuilder, ElectrumApi, Socks5Config};
 
 fn main() {
     // NOTE: This assumes Tor is running localy, with an unauthenticated Socks5 listening at
     // localhost:9050
+    let proxy = Socks5Config::new("127.0.0.1:9050");
+    let config = ConfigBuilder::new().socks5(Some(proxy)).build();
 
-    let client = Client::new("tcp://explorernuoc63nb.onion:110", Some("127.0.0.1:9050")).unwrap();
+    let client = Client::from_config("tcp://explorernuoc63nb.onion:110", config.clone()).unwrap();
     let res = client.server_features();
     println!("{:#?}", res);
 
     // works both with onion v2/v3 (if your Tor supports them)
-    let client = Client::new(
+    let client = Client::from_config(
         "tcp://explorerzydxu5ecjrkwceayqybizmpjjznk5izmitf2modhcusuqlid.onion:110",
-        Some("127.0.0.1:9050"),
+        config,
     )
     .unwrap();
     let res = client.server_features();

justfile

@@ -0,0 +1,34 @@
+alias b := build
+alias c := check
+alias f := fmt
+alias t := test
+alias p := pre-push
+
+_default:
+   @just --list
+
+# Build the project
+build:
+   cargo build
+
+# Check code: formatting, compilation, linting, doc comments, and commit signature
+check:
+   cargo +nightly fmt --all -- --check
+   cargo check --all-features --all-targets
+   cargo clippy --all-features --all-targets -- -D warnings
+   RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps
+   @[ "$(git log --pretty='format:%G?' -1 HEAD)" = "N" ] && \
+       echo "\n⚠️  Unsigned commit: BDK requires that commits be signed." || \
+       true
+
+# Format all code
+fmt:
+   cargo +nightly fmt
+
+# Run all tests on the workspace with all features
+test:
+   cargo test --all-features -- --test-threads=1
+
+# Run pre-push suite: format, check, and test
+pre-push: fmt check test
+

src/api.rs

@@ -1,17 +1,191 @@
 //! Electrum APIs
 
+use std::borrow::Borrow;
 use std::convert::TryInto;
+use std::ops::Deref;
 
 use bitcoin::consensus::encode::{deserialize, serialize};
-use bitcoin::{BlockHeader, Script, Transaction, Txid};
+use bitcoin::{block, Script, Transaction, Txid};
 
-use batch::Batch;
+use crate::batch::Batch;
-use types::*;
+use crate::types::*;
+
+impl<E: Deref> ElectrumApi for E
+where
+    E::Target: ElectrumApi,
+{
+    fn raw_call(
+        &self,
+        method_name: &str,
+        params: impl IntoIterator<Item = Param>,
+    ) -> Result<serde_json::Value, Error> {
+        (**self).raw_call(method_name, params)
+    }
+
+    fn batch_call(&self, batch: &Batch) -> Result<Vec<serde_json::Value>, Error> {
+        (**self).batch_call(batch)
+    }
+
+    fn block_headers_subscribe_raw(&self) -> Result<RawHeaderNotification, Error> {
+        (**self).block_headers_subscribe_raw()
+    }
+
+    fn block_headers_pop_raw(&self) -> Result<Option<RawHeaderNotification>, Error> {
+        (**self).block_headers_pop_raw()
+    }
+
+    fn block_header_raw(&self, height: usize) -> Result<Vec<u8>, Error> {
+        (**self).block_header_raw(height)
+    }
+
+    fn block_headers(&self, start_height: usize, count: usize) -> Result<GetHeadersRes, Error> {
+        (**self).block_headers(start_height, count)
+    }
+
+    fn estimate_fee(&self, number: usize) -> Result<f64, Error> {
+        (**self).estimate_fee(number)
+    }
+
+    fn relay_fee(&self) -> Result<f64, Error> {
+        (**self).relay_fee()
+    }
+
+    fn script_subscribe(&self, script: &Script) -> Result<Option<ScriptStatus>, Error> {
+        (**self).script_subscribe(script)
+    }
+
+    fn batch_script_subscribe<'s, I>(&self, scripts: I) -> Result<Vec<Option<ScriptStatus>>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>,
+    {
+        (**self).batch_script_subscribe(scripts)
+    }
+
+    fn script_unsubscribe(&self, script: &Script) -> Result<bool, Error> {
+        (**self).script_unsubscribe(script)
+    }
+
+    fn script_pop(&self, script: &Script) -> Result<Option<ScriptStatus>, Error> {
+        (**self).script_pop(script)
+    }
+
+    fn script_get_balance(&self, script: &Script) -> Result<GetBalanceRes, Error> {
+        (**self).script_get_balance(script)
+    }
+
+    fn batch_script_get_balance<'s, I>(&self, scripts: I) -> Result<Vec<GetBalanceRes>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>,
+    {
+        (**self).batch_script_get_balance(scripts)
+    }
+
+    fn script_get_history(&self, script: &Script) -> Result<Vec<GetHistoryRes>, Error> {
+        (**self).script_get_history(script)
+    }
+
+    fn batch_script_get_history<'s, I>(&self, scripts: I) -> Result<Vec<Vec<GetHistoryRes>>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>,
+    {
+        (**self).batch_script_get_history(scripts)
+    }
+
+    fn script_list_unspent(&self, script: &Script) -> Result<Vec<ListUnspentRes>, Error> {
+        (**self).script_list_unspent(script)
+    }
+
+    fn batch_script_list_unspent<'s, I>(
+        &self,
+        scripts: I,
+    ) -> Result<Vec<Vec<ListUnspentRes>>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>,
+    {
+        (**self).batch_script_list_unspent(scripts)
+    }
+
+    fn transaction_get_raw(&self, txid: &Txid) -> Result<Vec<u8>, Error> {
+        (**self).transaction_get_raw(txid)
+    }
+
+    fn batch_transaction_get_raw<'t, I>(&self, txids: I) -> Result<Vec<Vec<u8>>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'t Txid>,
+    {
+        (**self).batch_transaction_get_raw(txids)
+    }
+
+    fn batch_block_header_raw<I>(&self, heights: I) -> Result<Vec<Vec<u8>>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<u32>,
+    {
+        (**self).batch_block_header_raw(heights)
+    }
+
+    fn batch_estimate_fee<I>(&self, numbers: I) -> Result<Vec<f64>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<usize>,
+    {
+        (**self).batch_estimate_fee(numbers)
+    }
+
+    fn transaction_broadcast_raw(&self, raw_tx: &[u8]) -> Result<Txid, Error> {
+        (**self).transaction_broadcast_raw(raw_tx)
+    }
+
+    fn transaction_get_merkle(&self, txid: &Txid, height: usize) -> Result<GetMerkleRes, Error> {
+        (**self).transaction_get_merkle(txid, height)
+    }
+
+    fn batch_transaction_get_merkle<I>(
+        &self,
+        txids_and_heights: I,
+    ) -> Result<Vec<GetMerkleRes>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<(Txid, usize)>,
+    {
+        (**self).batch_transaction_get_merkle(txids_and_heights)
+    }
+
+    fn txid_from_pos(&self, height: usize, tx_pos: usize) -> Result<Txid, Error> {
+        (**self).txid_from_pos(height, tx_pos)
+    }
+
+    fn txid_from_pos_with_merkle(
+        &self,
+        height: usize,
+        tx_pos: usize,
+    ) -> Result<TxidFromPosRes, Error> {
+        (**self).txid_from_pos_with_merkle(height, tx_pos)
+    }
+
+    fn server_features(&self) -> Result<ServerFeaturesRes, Error> {
+        (**self).server_features()
+    }
+
+    fn ping(&self) -> Result<(), Error> {
+        (**self).ping()
+    }
+
+    #[cfg(feature = "debug-calls")]
+    fn calls_made(&self) -> Result<usize, Error> {
+        (**self).calls_made()
+    }
+}
 
 /// API calls exposed by an Electrum client
 pub trait ElectrumApi {
     /// Gets the block header for height `height`.
-    fn block_header(&self, height: usize) -> Result<BlockHeader, Error> {
+    fn block_header(&self, height: usize) -> Result<block::Header, Error> {
         Ok(deserialize(&self.block_header_raw(height)?)?)
     }
 
@@ -38,7 +212,8 @@ pub trait ElectrumApi {
     /// Takes a list of `txids` and returns a list of transactions.
     fn batch_transaction_get<'t, I>(&self, txids: I) -> Result<Vec<Transaction>, Error>
     where
-        I: IntoIterator<Item = &'t Txid>,
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'t Txid>,
     {
         self.batch_transaction_get_raw(txids)?
             .iter()
@@ -49,9 +224,10 @@ pub trait ElectrumApi {
     /// Batch version of [`block_header`](#method.block_header).
     ///
     /// Takes a list of `heights` of blocks and returns a list of headers.
-    fn batch_block_header<'s, I>(&self, heights: I) -> Result<Vec<BlockHeader>, Error>
+    fn batch_block_header<I>(&self, heights: I) -> Result<Vec<block::Header>, Error>
     where
-        I: IntoIterator<Item = u32>,
+        I: IntoIterator + Clone,
+        I::Item: Borrow<u32>,
     {
         self.batch_block_header_raw(heights)?
             .iter()
@@ -65,10 +241,17 @@ pub trait ElectrumApi {
         self.transaction_broadcast_raw(&buffer)
     }
 
+    /// Executes the requested API call returning the raw answer.
+    fn raw_call(
+        &self,
+        method_name: &str,
+        params: impl IntoIterator<Item = Param>,
+    ) -> Result<serde_json::Value, Error>;
+
     /// Execute a queue of calls stored in a [`Batch`](../batch/struct.Batch.html) struct. Returns
     /// `Ok()` **only if** all of the calls are successful. The order of the JSON `Value`s returned
     /// reflects the order in which the calls were made on the `Batch` struct.
-    fn batch_call(&self, batch: Batch) -> Result<Vec<serde_json::Value>, Error>;
+    fn batch_call(&self, batch: &Batch) -> Result<Vec<serde_json::Value>, Error>;
 
     /// Subscribes to notifications for new block headers, by sending a `blockchain.headers.subscribe` call and
     /// returns the current tip as raw bytes instead of deserializing them.
@@ -84,7 +267,7 @@ pub trait ElectrumApi {
     /// Tries to fetch `count` block headers starting from `start_height`.
     fn block_headers(&self, start_height: usize, count: usize) -> Result<GetHeadersRes, Error>;
 
-    /// Estimates the fee required in **Satoshis per kilobyte** to confirm a transaction in `number` blocks.
+    /// Estimates the fee required in **Bitcoin per kilobyte** to confirm a transaction in `number` blocks.
     fn estimate_fee(&self, number: usize) -> Result<f64, Error>;
 
     /// Returns the minimum accepted fee by the server's node in **Bitcoin, not Satoshi**.
@@ -99,6 +282,16 @@ pub trait ElectrumApi {
     /// already subscribed to the script.
     fn script_subscribe(&self, script: &Script) -> Result<Option<ScriptStatus>, Error>;
 
+    /// Batch version of [`script_subscribe`](#method.script_subscribe).
+    ///
+    /// Takes a list of scripts and returns a list of script status responses.
+    ///
+    /// Note you should pass a reference to a collection because otherwise an expensive clone is made
+    fn batch_script_subscribe<'s, I>(&self, scripts: I) -> Result<Vec<Option<ScriptStatus>>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>;
+
     /// Subscribes to notifications for activity on a specific *scriptPubKey*.
     ///
     /// Returns a `bool` with the server response when successful.
@@ -118,7 +311,8 @@ pub trait ElectrumApi {
     /// Takes a list of scripts and returns a list of balance responses.
     fn batch_script_get_balance<'s, I>(&self, scripts: I) -> Result<Vec<GetBalanceRes>, Error>
     where
-        I: IntoIterator<Item = &'s Script>;
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>;
 
     /// Returns the history for a *scriptPubKey*
     fn script_get_history(&self, script: &Script) -> Result<Vec<GetHistoryRes>, Error>;
@@ -128,7 +322,8 @@ pub trait ElectrumApi {
     /// Takes a list of scripts and returns a list of history responses.
     fn batch_script_get_history<'s, I>(&self, scripts: I) -> Result<Vec<Vec<GetHistoryRes>>, Error>
     where
-        I: IntoIterator<Item = &'s Script>;
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>;
 
     /// Returns the list of unspent outputs for a *scriptPubKey*
     fn script_list_unspent(&self, script: &Script) -> Result<Vec<ListUnspentRes>, Error>;
@@ -141,7 +336,8 @@ pub trait ElectrumApi {
         scripts: I,
     ) -> Result<Vec<Vec<ListUnspentRes>>, Error>
     where
-        I: IntoIterator<Item = &'s Script>;
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>;
 
     /// Gets the raw bytes of a transaction with `txid`. Returns an error if not found.
     fn transaction_get_raw(&self, txid: &Txid) -> Result<Vec<u8>, Error>;
@@ -151,22 +347,25 @@ pub trait ElectrumApi {
     /// Takes a list of `txids` and returns a list of transactions raw bytes.
     fn batch_transaction_get_raw<'t, I>(&self, txids: I) -> Result<Vec<Vec<u8>>, Error>
     where
-        I: IntoIterator<Item = &'t Txid>;
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'t Txid>;
 
     /// Batch version of [`block_header_raw`](#method.block_header_raw).
     ///
     /// Takes a list of `heights` of blocks and returns a list of block header raw bytes.
-    fn batch_block_header_raw<'s, I>(&self, heights: I) -> Result<Vec<Vec<u8>>, Error>
+    fn batch_block_header_raw<I>(&self, heights: I) -> Result<Vec<Vec<u8>>, Error>
     where
-        I: IntoIterator<Item = u32>;
+        I: IntoIterator + Clone,
+        I::Item: Borrow<u32>;
 
     /// Batch version of [`estimate_fee`](#method.estimate_fee).
     ///
     /// Takes a list of `numbers` of blocks and returns a list of fee required in
     /// **Satoshis per kilobyte** to confirm a transaction in the given number of blocks.
-    fn batch_estimate_fee<'s, I>(&self, numbers: I) -> Result<Vec<f64>, Error>
+    fn batch_estimate_fee<I>(&self, numbers: I) -> Result<Vec<f64>, Error>
     where
-        I: IntoIterator<Item = usize>;
+        I: IntoIterator + Clone,
+        I::Item: Borrow<usize>;
 
     /// Broadcasts the raw bytes of a transaction to the network.
     fn transaction_broadcast_raw(&self, raw_tx: &[u8]) -> Result<Txid, Error>;
@@ -174,6 +373,28 @@ pub trait ElectrumApi {
     /// Returns the merkle path for the transaction `txid` confirmed in the block at `height`.
     fn transaction_get_merkle(&self, txid: &Txid, height: usize) -> Result<GetMerkleRes, Error>;
 
+    /// Batch version of [`transaction_get_merkle`](#method.transaction_get_merkle).
+    ///
+    /// Take a list of `(txid, height)`, for transactions with `txid` confirmed in the block at `height`.
+    fn batch_transaction_get_merkle<I>(
+        &self,
+        txids_and_heights: I,
+    ) -> Result<Vec<GetMerkleRes>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<(Txid, usize)>;
+
+    /// Returns a transaction hash, given a block `height` and a `tx_pos` in the block.
+    fn txid_from_pos(&self, height: usize, tx_pos: usize) -> Result<Txid, Error>;
+
+    /// Returns a transaction hash and a merkle path, given a block `height` and a `tx_pos` in the
+    /// block.
+    fn txid_from_pos_with_merkle(
+        &self,
+        height: usize,
+        tx_pos: usize,
+    ) -> Result<TxidFromPosRes, Error>;
+
     /// Returns the capabilities of the server.
     fn server_features(&self) -> Result<ServerFeaturesRes, Error>;
 
@@ -183,5 +404,227 @@ pub trait ElectrumApi {
 
     #[cfg(feature = "debug-calls")]
     /// Returns the number of network calls made since the creation of the client.
-    fn calls_made(&self) -> usize;
+    fn calls_made(&self) -> Result<usize, Error>;
+}
+
+#[cfg(test)]
+mod test {
+    use std::{borrow::Cow, sync::Arc};
+
+    use super::ElectrumApi;
+
+    #[derive(Debug, Clone)]
+    struct FakeApi;
+
+    impl ElectrumApi for FakeApi {
+        fn raw_call(
+            &self,
+            _: &str,
+            _: impl IntoIterator<Item = super::Param>,
+        ) -> Result<serde_json::Value, super::Error> {
+            unreachable!()
+        }
+
+        fn batch_call(&self, _: &crate::Batch) -> Result<Vec<serde_json::Value>, super::Error> {
+            unreachable!()
+        }
+
+        fn block_headers_subscribe_raw(
+            &self,
+        ) -> Result<super::RawHeaderNotification, super::Error> {
+            unreachable!()
+        }
+
+        fn block_headers_pop_raw(
+            &self,
+        ) -> Result<Option<super::RawHeaderNotification>, super::Error> {
+            unreachable!()
+        }
+
+        fn block_header_raw(&self, _: usize) -> Result<Vec<u8>, super::Error> {
+            unreachable!()
+        }
+
+        fn block_headers(&self, _: usize, _: usize) -> Result<super::GetHeadersRes, super::Error> {
+            unreachable!()
+        }
+
+        fn estimate_fee(&self, _: usize) -> Result<f64, super::Error> {
+            unreachable!()
+        }
+
+        fn relay_fee(&self) -> Result<f64, super::Error> {
+            unreachable!()
+        }
+
+        fn script_subscribe(
+            &self,
+            _: &bitcoin::Script,
+        ) -> Result<Option<super::ScriptStatus>, super::Error> {
+            unreachable!()
+        }
+
+        fn batch_script_subscribe<'s, I>(
+            &self,
+            _: I,
+        ) -> Result<Vec<Option<super::ScriptStatus>>, super::Error>
+        where
+            I: IntoIterator + Clone,
+            I::Item: std::borrow::Borrow<&'s bitcoin::Script>,
+        {
+            unreachable!()
+        }
+
+        fn script_unsubscribe(&self, _: &bitcoin::Script) -> Result<bool, super::Error> {
+            unreachable!()
+        }
+
+        fn script_pop(
+            &self,
+            _: &bitcoin::Script,
+        ) -> Result<Option<super::ScriptStatus>, super::Error> {
+            unreachable!()
+        }
+
+        fn script_get_balance(
+            &self,
+            _: &bitcoin::Script,
+        ) -> Result<super::GetBalanceRes, super::Error> {
+            unreachable!()
+        }
+
+        fn batch_script_get_balance<'s, I>(
+            &self,
+            _: I,
+        ) -> Result<Vec<super::GetBalanceRes>, super::Error>
+        where
+            I: IntoIterator + Clone,
+            I::Item: std::borrow::Borrow<&'s bitcoin::Script>,
+        {
+            unreachable!()
+        }
+
+        fn script_get_history(
+            &self,
+            _: &bitcoin::Script,
+        ) -> Result<Vec<super::GetHistoryRes>, super::Error> {
+            unreachable!()
+        }
+
+        fn batch_script_get_history<'s, I>(
+            &self,
+            _: I,
+        ) -> Result<Vec<Vec<super::GetHistoryRes>>, super::Error>
+        where
+            I: IntoIterator + Clone,
+            I::Item: std::borrow::Borrow<&'s bitcoin::Script>,
+        {
+            unreachable!()
+        }
+
+        fn script_list_unspent(
+            &self,
+            _: &bitcoin::Script,
+        ) -> Result<Vec<super::ListUnspentRes>, super::Error> {
+            unreachable!()
+        }
+
+        fn batch_script_list_unspent<'s, I>(
+            &self,
+            _: I,
+        ) -> Result<Vec<Vec<super::ListUnspentRes>>, super::Error>
+        where
+            I: IntoIterator + Clone,
+            I::Item: std::borrow::Borrow<&'s bitcoin::Script>,
+        {
+            unreachable!()
+        }
+
+        fn transaction_get_raw(&self, _: &bitcoin::Txid) -> Result<Vec<u8>, super::Error> {
+            unreachable!()
+        }
+
+        fn batch_transaction_get_raw<'t, I>(&self, _: I) -> Result<Vec<Vec<u8>>, super::Error>
+        where
+            I: IntoIterator + Clone,
+            I::Item: std::borrow::Borrow<&'t bitcoin::Txid>,
+        {
+            unreachable!()
+        }
+
+        fn batch_block_header_raw<I>(&self, _: I) -> Result<Vec<Vec<u8>>, super::Error>
+        where
+            I: IntoIterator + Clone,
+            I::Item: std::borrow::Borrow<u32>,
+        {
+            unreachable!()
+        }
+
+        fn batch_estimate_fee<I>(&self, _: I) -> Result<Vec<f64>, super::Error>
+        where
+            I: IntoIterator + Clone,
+            I::Item: std::borrow::Borrow<usize>,
+        {
+            unreachable!()
+        }
+
+        fn transaction_broadcast_raw(&self, _: &[u8]) -> Result<bitcoin::Txid, super::Error> {
+            unreachable!()
+        }
+
+        fn transaction_get_merkle(
+            &self,
+            _: &bitcoin::Txid,
+            _: usize,
+        ) -> Result<super::GetMerkleRes, super::Error> {
+            unreachable!()
+        }
+
+        fn batch_transaction_get_merkle<I>(
+            &self,
+            _: I,
+        ) -> Result<Vec<crate::GetMerkleRes>, crate::Error>
+        where
+            I: IntoIterator + Clone,
+            I::Item: std::borrow::Borrow<(bitcoin::Txid, usize)>,
+        {
+            unreachable!()
+        }
+
+        fn txid_from_pos(&self, _: usize, _: usize) -> Result<bitcoin::Txid, super::Error> {
+            unreachable!()
+        }
+
+        fn txid_from_pos_with_merkle(
+            &self,
+            _: usize,
+            _: usize,
+        ) -> Result<super::TxidFromPosRes, super::Error> {
+            unreachable!()
+        }
+
+        fn server_features(&self) -> Result<super::ServerFeaturesRes, super::Error> {
+            unreachable!()
+        }
+
+        fn ping(&self) -> Result<(), super::Error> {
+            unreachable!()
+        }
+
+        #[cfg(feature = "debug-calls")]
+        fn calls_made(&self) -> Result<usize, super::Error> {
+            unreachable!()
+        }
+    }
+
+    fn is_impl<A: ElectrumApi>() {}
+
+    #[test]
+    fn deref() {
+        is_impl::<FakeApi>();
+        is_impl::<&FakeApi>();
+        is_impl::<Arc<FakeApi>>();
+        is_impl::<Box<FakeApi>>();
+        is_impl::<Cow<FakeApi>>();
+    }
 }

src/batch.rs

@@ -2,10 +2,9 @@
 //!
 //! This module contains definitions and helper functions used when making batch calls.
 
-use bitcoin::hashes::hex::ToHex;
 use bitcoin::{Script, Txid};
 
-use types::{Param, ToElectrumScriptHash};
+use crate::types::{Call, Param, ToElectrumScriptHash};
 
 /// Helper structure that caches all the requests before they are actually sent to the server.
 ///
@@ -17,11 +16,17 @@ use types::{Param, ToElectrumScriptHash};
 /// [`Client`](../client/struct.Client.html), like
 /// [`batch_script_get_balance`](../client/struct.Client.html#method.batch_script_get_balance) to ask the
 /// server for the balance of multiple scripts with a single request.
+#[derive(Default)]
 pub struct Batch {
-    calls: Vec<(String, Vec<Param>)>,
+    calls: Vec<Call>,
 }
 
 impl Batch {
+    /// Add a raw request to the batch queue
+    pub fn raw(&mut self, method: String, params: Vec<Param>) {
+        self.calls.push((method, params));
+    }
+
     /// Add one `blockchain.scripthash.listunspent` request to the batch queue
     pub fn script_list_unspent(&mut self, script: &Script) {
         let params = vec![Param::String(script.to_electrum_scripthash().to_hex())];
@@ -43,13 +48,31 @@ impl Batch {
             .push((String::from("blockchain.scripthash.get_balance"), params));
     }
 
+    /// Add one `blockchain.scripthash.listunspent` request to the batch queue
+    pub fn script_subscribe(&mut self, script: &Script) {
+        let params = vec![Param::String(script.to_electrum_scripthash().to_hex())];
+        self.calls
+            .push((String::from("blockchain.scripthash.subscribe"), params));
+    }
+
     /// Add one `blockchain.transaction.get` request to the batch queue
     pub fn transaction_get(&mut self, tx_hash: &Txid) {
-        let params = vec![Param::String(tx_hash.to_hex())];
+        let params = vec![Param::String(format!("{:x}", tx_hash))];
         self.calls
             .push((String::from("blockchain.transaction.get"), params));
     }
 
+    /// Add one `blockchain.transaction.get_merkle` request to the batch queue
+    pub fn transaction_get_merkle(&mut self, tx_hash_and_height: &(Txid, usize)) {
+        let (tx_hash, height) = tx_hash_and_height;
+        let params = vec![
+            Param::String(format!("{:x}", tx_hash)),
+            Param::Usize(*height),
+        ];
+        self.calls
+            .push((String::from("blockchain.transaction.get_merkle"), params));
+    }
+
     /// Add one `blockchain.estimatefee` request to the batch queue
     pub fn estimate_fee(&mut self, number: usize) {
         let params = vec![Param::Usize(number)];
@@ -63,6 +86,14 @@ impl Batch {
         self.calls
             .push((String::from("blockchain.block.header"), params));
     }
+
+    /// Returns an iterator on the batch
+    pub fn iter(&self) -> BatchIter<'_> {
+        BatchIter {
+            batch: self,
+            index: 0,
+        }
+    }
 }
 
 impl std::iter::IntoIterator for Batch {
@@ -74,8 +105,17 @@ impl std::iter::IntoIterator for Batch {
     }
 }
 
-impl std::default::Default for Batch {
+pub struct BatchIter<'a> {
-    fn default() -> Self {
+    batch: &'a Batch,
-        Batch { calls: Vec::new() }
+    index: usize,
+}
+
+impl<'a> std::iter::Iterator for BatchIter<'a> {
+    type Item = &'a (String, Vec<Param>);
+
+    fn next(&mut self) -> Option<Self::Item> {
+        let val = self.batch.calls.get(self.index);
+        self.index += 1;
+        val
     }
 }

src/client.rs

@@ -1,40 +1,145 @@
 //! Electrum Client
 
+use std::{borrow::Borrow, sync::RwLock};
+
+use log::{info, warn};
+
 use bitcoin::{Script, Txid};
 
-use api::ElectrumApi;
+use crate::api::ElectrumApi;
-use batch::Batch;
+use crate::batch::Batch;
-use raw_client::*;
+use crate::config::Config;
-use types::*;
+use crate::raw_client::*;
+use crate::types::*;
+use std::convert::TryFrom;
 
 /// Generalized Electrum client that supports multiple backends. This wraps
 /// [`RawClient`](client/struct.RawClient.html) and provides a more user-friendly
 /// constructor that can choose the right backend based on the url prefix.
 ///
-/// **This is only available with the `default` features.**
+/// **This is available only with the `default` features, or if `proxy` and one ssl implementation are enabled**
-#[cfg(feature = "default")]
+pub enum ClientType {
-pub enum Client {
+    #[allow(missing_docs)]
-    #[doc(hidden)]
     TCP(RawClient<ElectrumPlaintextStream>),
-    #[doc(hidden)]
+    #[allow(missing_docs)]
     SSL(RawClient<ElectrumSslStream>),
-    #[doc(hidden)]
+    #[allow(missing_docs)]
     Socks5(RawClient<ElectrumProxyStream>),
 }
 
+/// Generalized Electrum client that supports multiple backends. Can re-instantiate client_type if connections
+/// drops
+pub struct Client {
+    client_type: RwLock<ClientType>,
+    config: Config,
+    url: String,
+}
+
 macro_rules! impl_inner_call {
     ( $self:expr, $name:ident $(, $args:expr)* ) => {
-        match $self {
+    {
-            Client::TCP(inner) => inner.$name( $($args, )* ),
+        let mut errors = vec![];
-            Client::SSL(inner) => inner.$name( $($args, )* ),
+        loop {
-            Client::Socks5(inner) => inner.$name( $($args, )* ),
+            let read_client = $self.client_type.read().unwrap();
+            let res = match &*read_client {
+                ClientType::TCP(inner) => inner.$name( $($args, )* ),
+                ClientType::SSL(inner) => inner.$name( $($args, )* ),
+                ClientType::Socks5(inner) => inner.$name( $($args, )* ),
+            };
+            drop(read_client);
+            match res {
+                Ok(val) => return Ok(val),
+                Err(Error::Protocol(_) | Error::AlreadySubscribed(_)) => {
+                    return res;
+                },
+                Err(e) => {
+                    let failed_attempts = errors.len() + 1;
+
+                    if retries_exhausted(failed_attempts, $self.config.retry()) {
+                        warn!("call '{}' failed after {} attempts", stringify!($name), failed_attempts);
+                        return Err(Error::AllAttemptsErrored(errors));
+                    }
+
+                    warn!("call '{}' failed with {}, retry: {}/{}", stringify!($name), e, failed_attempts, $self.config.retry());
+
+                    errors.push(e);
+
+                    // Only one thread will try to recreate the client getting the write lock,
+                    // other eventual threads will get Err and will block at the beginning of
+                    // previous loop when trying to read()
+                    if let Ok(mut write_client) = $self.client_type.try_write() {
+                        loop {
+                            std::thread::sleep(std::time::Duration::from_secs((1 << errors.len()).min(30) as u64));
+                            match ClientType::from_config(&$self.url, &$self.config) {
+                                Ok(new_client) => {
+                                    info!("Succesfully created new client");
+                                    *write_client = new_client;
+                                    break;
+                                },
+                                Err(e) => {
+                                    let failed_attempts = errors.len() + 1;
+
+                                    if retries_exhausted(failed_attempts, $self.config.retry()) {
+                                        warn!("re-creating client failed after {} attempts", failed_attempts);
+                                        return Err(Error::AllAttemptsErrored(errors));
+                                    }
+
+                                    warn!("re-creating client failed with {}, retry: {}/{}", e, failed_attempts, $self.config.retry());
+
+                                    errors.push(e);
+                                }
+                            }
+                        }
+                    }
+                },
+            }
+        }}
+    }
+}
+
+fn retries_exhausted(failed_attempts: usize, configured_retries: u8) -> bool {
+    match u8::try_from(failed_attempts) {
+        Ok(failed_attempts) => failed_attempts > configured_retries,
+        Err(_) => true, // if the usize doesn't fit into a u8, we definitely exhausted our retries
+    }
+}
+
+impl ClientType {
+    /// Constructor that supports multiple backends and allows configuration through
+    /// the [Config]
+    pub fn from_config(url: &str, config: &Config) -> Result<Self, Error> {
+        if url.starts_with("ssl://") {
+            let url = url.replacen("ssl://", "", 1);
+            let client = match config.socks5() {
+                Some(socks5) => RawClient::new_proxy_ssl(
+                    url.as_str(),
+                    config.validate_domain(),
+                    socks5,
+                    config.timeout(),
+                )?,
+                None => {
+                    RawClient::new_ssl(url.as_str(), config.validate_domain(), config.timeout())?
+                }
+            };
+
+            Ok(ClientType::SSL(client))
+        } else {
+            let url = url.replacen("tcp://", "", 1);
+
+            Ok(match config.socks5().as_ref() {
+                None => ClientType::TCP(RawClient::new(url.as_str(), config.timeout())?),
+                Some(socks5) => ClientType::Socks5(RawClient::new_proxy(
+                    url.as_str(),
+                    socks5,
+                    config.timeout(),
+                )?),
+            })
         }
     }
 }
 
-#[cfg(feature = "default")]
 impl Client {
-    /// Generic constructor that supports multiple backends and, optionally, a socks5 proxy.
+    /// Default constructor supporting multiple backends by providing a prefix
     ///
     /// Supported prefixes are:
     /// - tcp:// for a TCP plaintext client.
@@ -42,38 +147,42 @@ impl Client {
     ///
     /// If no prefix is specified, then `tcp://` is assumed.
     ///
-    /// The `socks5` argument can optionally be prefixed with `socks5://`.
+    /// See [Client::from_config] for more configuration options
-    ///
+    pub fn new(url: &str) -> Result<Self, Error> {
-    /// **NOTE**: SSL-over-socks5 is currently not supported and will generate a runtime error.
+        Self::from_config(url, Config::default())
-    pub fn new(url: &str, socks5: Option<&str>) -> Result<Self, Error> {
+    }
-        let socks5 = socks5.map(|s| s.replacen("socks5://", "", 1));
 
-        if url.starts_with("ssl://") {
+    /// Generic constructor that supports multiple backends and allows configuration through
-            if socks5.is_some() {
+    /// the [Config]
-                return Err(Error::SSLOverSocks5);
+    pub fn from_config(url: &str, config: Config) -> Result<Self, Error> {
-            }
+        let client_type = RwLock::new(ClientType::from_config(url, &config)?);
 
-            let url = url.replacen("ssl://", "", 1);
+        Ok(Client {
-            let client = RawClient::new_ssl(url.as_str(), true)?;
+            client_type,
-
+            config,
-            Ok(Client::SSL(client))
+            url: url.to_string(),
-        } else {
+        })
-            let url = url.replacen("tcp://", "", 1);
-
-            let client = match socks5 {
-                None => Client::TCP(RawClient::new(url.as_str())?),
-                Some(socks5) => Client::Socks5(RawClient::new_proxy(url.as_str(), socks5)?),
-            };
-
-            Ok(client)
-        }
     }
 }
 
-#[cfg(feature = "default")]
 impl ElectrumApi for Client {
     #[inline]
-    fn batch_call(&self, batch: Batch) -> Result<Vec<serde_json::Value>, Error> {
+    fn raw_call(
+        &self,
+        method_name: &str,
+        params: impl IntoIterator<Item = Param>,
+    ) -> Result<serde_json::Value, Error> {
+        // We can't passthrough this method to the inner client because it would require the
+        // `params` argument to also be `Copy` (because it's used multiple times for multiple
+        // retries). To avoid adding this extra trait bound we instead re-direct this call to the internal
+        // `RawClient::internal_raw_call_with_vec` method.
+
+        let vec = params.into_iter().collect::<Vec<Param>>();
+        impl_inner_call!(self, internal_raw_call_with_vec, method_name, vec.clone());
+    }
+
+    #[inline]
+    fn batch_call(&self, batch: &Batch) -> Result<Vec<serde_json::Value>, Error> {
         impl_inner_call!(self, batch_call, batch)
     }
 
@@ -112,6 +221,15 @@ impl ElectrumApi for Client {
         impl_inner_call!(self, script_subscribe, script)
     }
 
+    #[inline]
+    fn batch_script_subscribe<'s, I>(&self, scripts: I) -> Result<Vec<Option<ScriptStatus>>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>,
+    {
+        impl_inner_call!(self, batch_script_subscribe, scripts.clone())
+    }
+
     #[inline]
     fn script_unsubscribe(&self, script: &Script) -> Result<bool, Error> {
         impl_inner_call!(self, script_unsubscribe, script)
@@ -130,9 +248,10 @@ impl ElectrumApi for Client {
     #[inline]
     fn batch_script_get_balance<'s, I>(&self, scripts: I) -> Result<Vec<GetBalanceRes>, Error>
     where
-        I: IntoIterator<Item = &'s Script>,
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>,
     {
-        impl_inner_call!(self, batch_script_get_balance, scripts)
+        impl_inner_call!(self, batch_script_get_balance, scripts.clone())
     }
 
     #[inline]
@@ -143,9 +262,10 @@ impl ElectrumApi for Client {
     #[inline]
     fn batch_script_get_history<'s, I>(&self, scripts: I) -> Result<Vec<Vec<GetHistoryRes>>, Error>
     where
-        I: IntoIterator<Item = &'s Script>,
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>,
     {
-        impl_inner_call!(self, batch_script_get_history, scripts)
+        impl_inner_call!(self, batch_script_get_history, scripts.clone())
     }
 
     #[inline]
@@ -159,9 +279,10 @@ impl ElectrumApi for Client {
         scripts: I,
     ) -> Result<Vec<Vec<ListUnspentRes>>, Error>
     where
-        I: IntoIterator<Item = &'s Script>,
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'s Script>,
     {
-        impl_inner_call!(self, batch_script_list_unspent, scripts)
+        impl_inner_call!(self, batch_script_list_unspent, scripts.clone())
     }
 
     #[inline]
@@ -172,25 +293,28 @@ impl ElectrumApi for Client {
     #[inline]
     fn batch_transaction_get_raw<'t, I>(&self, txids: I) -> Result<Vec<Vec<u8>>, Error>
     where
-        I: IntoIterator<Item = &'t Txid>,
+        I: IntoIterator + Clone,
+        I::Item: Borrow<&'t Txid>,
     {
-        impl_inner_call!(self, batch_transaction_get_raw, txids)
+        impl_inner_call!(self, batch_transaction_get_raw, txids.clone())
     }
 
     #[inline]
     fn batch_block_header_raw<'s, I>(&self, heights: I) -> Result<Vec<Vec<u8>>, Error>
     where
-        I: IntoIterator<Item = u32>,
+        I: IntoIterator + Clone,
+        I::Item: Borrow<u32>,
     {
-        impl_inner_call!(self, batch_block_header_raw, heights)
+        impl_inner_call!(self, batch_block_header_raw, heights.clone())
     }
 
     #[inline]
     fn batch_estimate_fee<'s, I>(&self, numbers: I) -> Result<Vec<f64>, Error>
     where
-        I: IntoIterator<Item = usize>,
+        I: IntoIterator + Clone,
+        I::Item: Borrow<usize>,
     {
-        impl_inner_call!(self, batch_estimate_fee, numbers)
+        impl_inner_call!(self, batch_estimate_fee, numbers.clone())
     }
 
     #[inline]
@@ -203,6 +327,36 @@ impl ElectrumApi for Client {
         impl_inner_call!(self, transaction_get_merkle, txid, height)
     }
 
+    #[inline]
+    fn batch_transaction_get_merkle<I>(
+        &self,
+        txids_and_heights: I,
+    ) -> Result<Vec<GetMerkleRes>, Error>
+    where
+        I: IntoIterator + Clone,
+        I::Item: Borrow<(Txid, usize)>,
+    {
+        impl_inner_call!(
+            self,
+            batch_transaction_get_merkle,
+            txids_and_heights.clone()
+        )
+    }
+
+    #[inline]
+    fn txid_from_pos(&self, height: usize, tx_pos: usize) -> Result<Txid, Error> {
+        impl_inner_call!(self, txid_from_pos, height, tx_pos)
+    }
+
+    #[inline]
+    fn txid_from_pos_with_merkle(
+        &self,
+        height: usize,
+        tx_pos: usize,
+    ) -> Result<TxidFromPosRes, Error> {
+        impl_inner_call!(self, txid_from_pos_with_merkle, height, tx_pos)
+    }
+
     #[inline]
     fn server_features(&self) -> Result<ServerFeaturesRes, Error> {
         impl_inner_call!(self, server_features)
@@ -215,7 +369,92 @@ impl ElectrumApi for Client {
 
     #[inline]
     #[cfg(feature = "debug-calls")]
-    fn calls_made(&self) -> usize {
+    fn calls_made(&self) -> Result<usize, Error> {
         impl_inner_call!(self, calls_made)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn more_failed_attempts_than_retries_means_exhausted() {
+        let exhausted = retries_exhausted(10, 5);
+
+        assert!(exhausted)
+    }
+
+    #[test]
+    fn failed_attempts_bigger_than_u8_means_exhausted() {
+        let failed_attempts = u8::MAX as usize + 1;
+
+        let exhausted = retries_exhausted(failed_attempts, u8::MAX);
+
+        assert!(exhausted)
+    }
+
+    #[test]
+    fn less_failed_attempts_means_not_exhausted() {
+        let exhausted = retries_exhausted(2, 5);
+
+        assert!(!exhausted)
+    }
+
+    #[test]
+    fn attempts_equals_retries_means_not_exhausted_yet() {
+        let exhausted = retries_exhausted(2, 2);
+
+        assert!(!exhausted)
+    }
+
+    #[test]
+    #[ignore]
+    fn test_local_timeout() {
+        // This test assumes a couple things:
+        // - that `localhost` is resolved to two IP addresses, `127.0.0.1` and `::1` (with the v6
+        //   one having higher priority)
+        // - that the system silently drops packets to `[::1]:60000` or a different port if
+        //   specified through `TEST_ELECTRUM_TIMEOUT_PORT`
+        //
+        //   this can be setup with: ip6tables -I INPUT 1 -p tcp -d ::1 --dport 60000 -j DROP
+        //   and removed with:       ip6tables -D INPUT -p tcp -d ::1 --dport 60000 -j DROP
+        //
+        // The test tries to create a client to `localhost` and expects it to succeed, but only
+        // after at least 2 seconds have passed which is roughly the timeout time for the first
+        // try.
+
+        use std::net::TcpListener;
+        use std::sync::mpsc::channel;
+        use std::time::{Duration, Instant};
+
+        let endpoint =
+            std::env::var("TEST_ELECTRUM_TIMEOUT_PORT").unwrap_or("localhost:60000".into());
+        let (sender, receiver) = channel();
+
+        std::thread::spawn(move || {
+            let listener = TcpListener::bind("127.0.0.1:60000").unwrap();
+            sender.send(()).unwrap();
+
+            for _stream in listener.incoming() {
+                std::thread::sleep(Duration::from_secs(60))
+            }
+        });
+
+        receiver
+            .recv_timeout(Duration::from_secs(5))
+            .expect("Can't start local listener");
+
+        let now = Instant::now();
+        let client = Client::from_config(
+            &endpoint,
+            crate::config::ConfigBuilder::new()
+                .timeout(Some(Duration::from_secs(5)))
+                .build(),
+        );
+        let elapsed = now.elapsed();
+
+        assert!(client.is_ok());
+        assert!(elapsed > Duration::from_secs(2));
+    }
+}

src/config.rs

@@ -0,0 +1,149 @@
+use std::time::Duration;
+
+/// Configuration for an electrum client
+///
+/// Refer to [`Client::from_config`] and [`ClientType::from_config`].
+///
+/// [`Client::from_config`]: crate::Client::from_config
+/// [`ClientType::from_config`]: crate::ClientType::from_config
+#[derive(Debug, Clone)]
+pub struct Config {
+    /// Proxy socks5 configuration, default None
+    socks5: Option<Socks5Config>,
+    /// timeout in seconds, default None (depends on TcpStream default)
+    timeout: Option<Duration>,
+    /// number of retry if any error, default 1
+    retry: u8,
+    /// when ssl, validate the domain, default true
+    validate_domain: bool,
+}
+
+/// Configuration for Socks5
+#[derive(Debug, Clone)]
+pub struct Socks5Config {
+    /// The address of the socks5 service
+    pub addr: String,
+    /// Optional credential for the service
+    pub credentials: Option<Socks5Credential>,
+}
+
+/// Credential for the proxy
+#[derive(Debug, Clone)]
+pub struct Socks5Credential {
+    pub username: String,
+    pub password: String,
+}
+
+/// [Config] Builder
+pub struct ConfigBuilder {
+    config: Config,
+}
+
+impl ConfigBuilder {
+    /// Create a builder with a default config, equivalent to [ConfigBuilder::default()]
+    pub fn new() -> Self {
+        ConfigBuilder {
+            config: Config::default(),
+        }
+    }
+
+    /// Set the socks5 config if Some, it accept an `Option` because it's easier for the caller to use
+    /// in a method chain
+    pub fn socks5(mut self, socks5_config: Option<Socks5Config>) -> Self {
+        self.config.socks5 = socks5_config;
+        self
+    }
+
+    /// Sets the timeout
+    pub fn timeout(mut self, timeout: Option<Duration>) -> Self {
+        self.config.timeout = timeout;
+        self
+    }
+
+    /// Sets the retry attempts number
+    pub fn retry(mut self, retry: u8) -> Self {
+        self.config.retry = retry;
+        self
+    }
+
+    /// Sets if the domain has to be validated
+    pub fn validate_domain(mut self, validate_domain: bool) -> Self {
+        self.config.validate_domain = validate_domain;
+        self
+    }
+
+    /// Return the config and consume the builder
+    pub fn build(self) -> Config {
+        self.config
+    }
+}
+
+impl Default for ConfigBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Socks5Config {
+    /// Socks5Config constructor without credentials
+    pub fn new(addr: impl ToString) -> Self {
+        let addr = addr.to_string().replacen("socks5://", "", 1);
+        Socks5Config {
+            addr,
+            credentials: None,
+        }
+    }
+
+    /// Socks5Config constructor if we have credentials
+    pub fn with_credentials(addr: impl ToString, username: String, password: String) -> Self {
+        let mut config = Socks5Config::new(addr);
+        config.credentials = Some(Socks5Credential { username, password });
+        config
+    }
+}
+
+impl Config {
+    /// Get the configuration for `socks5`
+    ///
+    /// Set this with [`ConfigBuilder::socks5`]
+    pub fn socks5(&self) -> &Option<Socks5Config> {
+        &self.socks5
+    }
+
+    /// Get the configuration for `retry`
+    ///
+    /// Set this with [`ConfigBuilder::retry`]
+    pub fn retry(&self) -> u8 {
+        self.retry
+    }
+
+    /// Get the configuration for `timeout`
+    ///
+    /// Set this with [`ConfigBuilder::timeout`]
+    pub fn timeout(&self) -> Option<Duration> {
+        self.timeout
+    }
+
+    /// Get the configuration for `validate_domain`
+    ///
+    /// Set this with [`ConfigBuilder::validate_domain`]
+    pub fn validate_domain(&self) -> bool {
+        self.validate_domain
+    }
+
+    /// Convenience method for calling [`ConfigBuilder::new`]
+    pub fn builder() -> ConfigBuilder {
+        ConfigBuilder::new()
+    }
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        Config {
+            socks5: None,
+            timeout: None,
+            retry: 1,
+            validate_domain: true,
+        }
+    }
+}

src/lib.rs

@@ -14,7 +14,7 @@
 //! ```no_run
 //! use electrum_client::{Client, ElectrumApi};
 //!
-//! let mut client = Client::new("tcp://electrum.blockstream.info:50001", None)?;
+//! let mut client = Client::new("tcp://electrum.blockstream.info:50001")?;
 //! let response = client.server_features()?;
 //! # Ok::<(), electrum_client::Error>(())
 //! ```
@@ -25,27 +25,59 @@ extern crate log;
 #[cfg(feature = "use-openssl")]
 extern crate openssl;
 #[cfg(all(
-    any(feature = "default", feature = "use-rustls"),
+    any(
+        feature = "default",
+        feature = "use-rustls",
+        feature = "use-rustls-ring"
+    ),
     not(feature = "use-openssl")
 ))]
 extern crate rustls;
 extern crate serde;
 extern crate serde_json;
-#[cfg(any(feature = "default", feature = "proxy"))]
+
-extern crate socks;
+#[cfg(any(
-#[cfg(any(feature = "use-rustls", feature = "default"))]
+    feature = "default",
-extern crate webpki;
+    feature = "use-rustls",
-#[cfg(any(feature = "use-rustls", feature = "default"))]
+    feature = "use-rustls-ring"
+))]
 extern crate webpki_roots;
 
+#[cfg(any(feature = "default", feature = "proxy"))]
+extern crate byteorder;
+
+#[cfg(all(unix, any(feature = "default", feature = "proxy")))]
+extern crate libc;
+#[cfg(all(windows, any(feature = "default", feature = "proxy")))]
+extern crate winapi;
+
+#[cfg(any(feature = "default", feature = "proxy"))]
+pub mod socks;
+
 mod api;
 mod batch;
+
+#[cfg(any(
+    all(feature = "proxy", feature = "use-openssl"),
+    all(feature = "proxy", feature = "use-rustls"),
+    all(feature = "proxy", feature = "use-rustls-ring")
+))]
 pub mod client;
+
+mod config;
+
 pub mod raw_client;
 mod stream;
 mod types;
+pub mod utils;
 
 pub use api::ElectrumApi;
 pub use batch::Batch;
+#[cfg(any(
+    all(feature = "proxy", feature = "use-openssl"),
+    all(feature = "proxy", feature = "use-rustls"),
+    all(feature = "proxy", feature = "use-rustls-ring")
+))]
 pub use client::*;
+pub use config::{Config, ConfigBuilder, Socks5Config};
 pub use types::*;

src/socks/mod.rs

@@ -0,0 +1,162 @@
+//! SOCKS proxy clients
+
+use std::io;
+use std::net::{Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6, ToSocketAddrs};
+use std::vec;
+
+pub use self::v4::{Socks4Listener, Socks4Stream};
+pub use self::v5::{Socks5Datagram, Socks5Listener, Socks5Stream};
+
+mod v4;
+mod v5;
+mod writev;
+
+/// A description of a connection target.
+#[derive(Debug, Clone)]
+pub enum TargetAddr {
+    /// Connect to an IP address.
+    Ip(SocketAddr),
+    /// Connect to a fully qualified domain name.
+    ///
+    /// The domain name will be passed along to the proxy server and DNS lookup
+    /// will happen there.
+    Domain(String, u16),
+}
+
+impl ToSocketAddrs for TargetAddr {
+    type Iter = Iter;
+
+    fn to_socket_addrs(&self) -> io::Result<Iter> {
+        let inner = match *self {
+            TargetAddr::Ip(addr) => IterInner::Ip(Some(addr)),
+            TargetAddr::Domain(ref domain, port) => {
+                let it = (&**domain, port).to_socket_addrs()?;
+                IterInner::Domain(it)
+            }
+        };
+        Ok(Iter(inner))
+    }
+}
+
+enum IterInner {
+    Ip(Option<SocketAddr>),
+    Domain(vec::IntoIter<SocketAddr>),
+}
+
+/// An iterator over `SocketAddr`s associated with a `TargetAddr`.
+pub struct Iter(IterInner);
+
+impl Iterator for Iter {
+    type Item = SocketAddr;
+
+    fn next(&mut self) -> Option<SocketAddr> {
+        match self.0 {
+            IterInner::Ip(ref mut addr) => addr.take(),
+            IterInner::Domain(ref mut it) => it.next(),
+        }
+    }
+}
+
+/// A trait for objects that can be converted to `TargetAddr`.
+pub trait ToTargetAddr {
+    /// Converts the value of `self` to a `TargetAddr`.
+    fn to_target_addr(&self) -> io::Result<TargetAddr>;
+}
+
+impl ToTargetAddr for TargetAddr {
+    fn to_target_addr(&self) -> io::Result<TargetAddr> {
+        Ok(self.clone())
+    }
+}
+
+impl ToTargetAddr for SocketAddr {
+    fn to_target_addr(&self) -> io::Result<TargetAddr> {
+        Ok(TargetAddr::Ip(*self))
+    }
+}
+
+impl ToTargetAddr for SocketAddrV4 {
+    fn to_target_addr(&self) -> io::Result<TargetAddr> {
+        SocketAddr::V4(*self).to_target_addr()
+    }
+}
+
+impl ToTargetAddr for SocketAddrV6 {
+    fn to_target_addr(&self) -> io::Result<TargetAddr> {
+        SocketAddr::V6(*self).to_target_addr()
+    }
+}
+
+impl ToTargetAddr for (Ipv4Addr, u16) {
+    fn to_target_addr(&self) -> io::Result<TargetAddr> {
+        SocketAddrV4::new(self.0, self.1).to_target_addr()
+    }
+}
+
+impl ToTargetAddr for (Ipv6Addr, u16) {
+    fn to_target_addr(&self) -> io::Result<TargetAddr> {
+        SocketAddrV6::new(self.0, self.1, 0, 0).to_target_addr()
+    }
+}
+
+impl ToTargetAddr for (&str, u16) {
+    fn to_target_addr(&self) -> io::Result<TargetAddr> {
+        // try to parse as an IP first
+        if let Ok(addr) = self.0.parse::<Ipv4Addr>() {
+            return (addr, self.1).to_target_addr();
+        }
+
+        if let Ok(addr) = self.0.parse::<Ipv6Addr>() {
+            return (addr, self.1).to_target_addr();
+        }
+
+        Ok(TargetAddr::Domain(self.0.to_owned(), self.1))
+    }
+}
+
+impl ToTargetAddr for &str {
+    fn to_target_addr(&self) -> io::Result<TargetAddr> {
+        // try to parse as an IP first
+        if let Ok(addr) = self.parse::<SocketAddrV4>() {
+            return addr.to_target_addr();
+        }
+
+        if let Ok(addr) = self.parse::<SocketAddrV6>() {
+            return addr.to_target_addr();
+        }
+
+        // split the string by ':' and convert the second part to u16
+        let mut parts_iter = self.rsplitn(2, ':');
+        let port_str = match parts_iter.next() {
+            Some(s) => s,
+            None => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "invalid socket address",
+                ))
+            }
+        };
+
+        let host = match parts_iter.next() {
+            Some(s) => s,
+            None => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "invalid socket address",
+                ))
+            }
+        };
+
+        let port: u16 = match port_str.parse() {
+            Ok(p) => p,
+            Err(_) => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "invalid port value",
+                ))
+            }
+        };
+
+        (host, port).to_target_addr()
+    }
+}

src/socks/v4.rs

@@ -0,0 +1,280 @@
+use byteorder::{BigEndian, ReadBytesExt, WriteBytesExt};
+use std::io::{self, Read, Write};
+use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, SocketAddrV6, TcpStream, ToSocketAddrs};
+
+use super::{TargetAddr, ToTargetAddr};
+
+fn read_response(socket: &mut TcpStream) -> io::Result<SocketAddrV4> {
+    let mut response = [0u8; 8];
+    socket.read_exact(&mut response)?;
+    let mut response = &response[..];
+
+    if response.read_u8()? != 0 {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            "invalid response version",
+        ));
+    }
+
+    match response.read_u8()? {
+        90 => {}
+        91 => return Err(io::Error::other("request rejected or failed")),
+        92 => {
+            return Err(io::Error::new(
+                io::ErrorKind::PermissionDenied,
+                "request rejected because SOCKS server cannot connect to \
+                                       idnetd on the client",
+            ))
+        }
+        93 => {
+            return Err(io::Error::new(
+                io::ErrorKind::PermissionDenied,
+                "request rejected because the client program and identd \
+                                       report different user-ids",
+            ))
+        }
+        _ => {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "invalid response code",
+            ))
+        }
+    }
+
+    let port = response.read_u16::<BigEndian>()?;
+    let ip = Ipv4Addr::from(response.read_u32::<BigEndian>()?);
+
+    Ok(SocketAddrV4::new(ip, port))
+}
+
+/// A SOCKS4 client.
+#[derive(Debug)]
+pub struct Socks4Stream {
+    socket: TcpStream,
+    proxy_addr: SocketAddrV4,
+}
+
+impl Socks4Stream {
+    /// Connects to a target server through a SOCKS4 proxy.
+    ///
+    /// # Note
+    ///
+    /// If `target` is a `TargetAddr::Domain`, the domain name will be forwarded
+    /// to the proxy server using the SOCKS4A protocol extension. If the proxy
+    /// server does not support SOCKS4A, consider performing the DNS lookup
+    /// locally and passing a `TargetAddr::Ip`.
+    pub fn connect<T, U>(proxy: T, target: U, userid: &str) -> io::Result<Socks4Stream>
+    where
+        T: ToSocketAddrs,
+        U: ToTargetAddr,
+    {
+        Self::connect_raw(1, proxy, target, userid)
+    }
+
+    fn connect_raw<T, U>(command: u8, proxy: T, target: U, userid: &str) -> io::Result<Socks4Stream>
+    where
+        T: ToSocketAddrs,
+        U: ToTargetAddr,
+    {
+        let mut socket = TcpStream::connect(proxy)?;
+
+        let target = target.to_target_addr()?;
+
+        let mut packet = vec![];
+        let _ = packet.write_u8(4); // version
+        let _ = packet.write_u8(command); // command code
+        match target.to_target_addr()? {
+            TargetAddr::Ip(addr) => {
+                let addr = match addr {
+                    SocketAddr::V4(addr) => addr,
+                    SocketAddr::V6(_) => {
+                        return Err(io::Error::new(
+                            io::ErrorKind::InvalidInput,
+                            "SOCKS4 does not support IPv6",
+                        ));
+                    }
+                };
+                let _ = packet.write_u16::<BigEndian>(addr.port());
+                let _ = packet.write_u32::<BigEndian>((*addr.ip()).into());
+                let _ = packet.write_all(userid.as_bytes());
+                let _ = packet.write_u8(0);
+            }
+            TargetAddr::Domain(ref host, port) => {
+                let _ = packet.write_u16::<BigEndian>(port);
+                let _ = packet.write_u32::<BigEndian>(Ipv4Addr::new(0, 0, 0, 1).into());
+                let _ = packet.write_all(userid.as_bytes());
+                let _ = packet.write_u8(0);
+                packet.extend(host.as_bytes());
+                let _ = packet.write_u8(0);
+            }
+        }
+
+        socket.write_all(&packet)?;
+        let proxy_addr = read_response(&mut socket)?;
+
+        Ok(Socks4Stream { socket, proxy_addr })
+    }
+
+    /// Returns the proxy-side address of the connection between the proxy and
+    /// target server.
+    pub fn proxy_addr(&self) -> SocketAddrV4 {
+        self.proxy_addr
+    }
+
+    /// Returns a shared reference to the inner `TcpStream`.
+    pub fn get_ref(&self) -> &TcpStream {
+        &self.socket
+    }
+
+    /// Returns a mutable reference to the inner `TcpStream`.
+    pub fn get_mut(&mut self) -> &mut TcpStream {
+        &mut self.socket
+    }
+
+    /// Consumes the `Socks4Stream`, returning the inner `TcpStream`.
+    pub fn into_inner(self) -> TcpStream {
+        self.socket
+    }
+}
+
+impl Read for Socks4Stream {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        self.socket.read(buf)
+    }
+}
+
+impl Read for &Socks4Stream {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        (&self.socket).read(buf)
+    }
+}
+
+impl Write for Socks4Stream {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        self.socket.write(buf)
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        self.socket.flush()
+    }
+}
+
+impl Write for &Socks4Stream {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        (&self.socket).write(buf)
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        (&self.socket).flush()
+    }
+}
+
+/// A SOCKS4 BIND client.
+#[derive(Debug)]
+pub struct Socks4Listener(Socks4Stream);
+
+impl Socks4Listener {
+    /// Initiates a BIND request to the specified proxy.
+    ///
+    /// The proxy will filter incoming connections based on the value of
+    /// `target`.
+    pub fn bind<T, U>(proxy: T, target: U, userid: &str) -> io::Result<Socks4Listener>
+    where
+        T: ToSocketAddrs,
+        U: ToTargetAddr,
+    {
+        Socks4Stream::connect_raw(2, proxy, target, userid).map(Socks4Listener)
+    }
+
+    /// The address of the proxy-side TCP listener.
+    ///
+    /// This should be forwarded to the remote process, which should open a
+    /// connection to it.
+    pub fn proxy_addr(&self) -> io::Result<SocketAddr> {
+        if self.0.proxy_addr.ip().octets() != [0, 0, 0, 0] {
+            Ok(SocketAddr::V4(self.0.proxy_addr()))
+        } else {
+            let port = self.0.proxy_addr.port();
+            let peer = match self.0.socket.peer_addr()? {
+                SocketAddr::V4(addr) => SocketAddr::V4(SocketAddrV4::new(*addr.ip(), port)),
+                SocketAddr::V6(addr) => SocketAddr::V6(SocketAddrV6::new(*addr.ip(), port, 0, 0)),
+            };
+            Ok(peer)
+        }
+    }
+
+    /// Waits for the remote process to connect to the proxy server.
+    ///
+    /// The value of `proxy_addr` should be forwarded to the remote process
+    /// before this method is called.
+    pub fn accept(mut self) -> io::Result<Socks4Stream> {
+        self.0.proxy_addr = read_response(&mut self.0.socket)?;
+        Ok(self.0)
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use std::io::{Read, Write};
+    use std::net::{SocketAddr, SocketAddrV4, TcpStream, ToSocketAddrs};
+
+    use super::*;
+
+    fn google_ip() -> SocketAddrV4 {
+        "google.com:80"
+            .to_socket_addrs()
+            .unwrap()
+            .filter_map(|a| match a {
+                SocketAddr::V4(a) => Some(a),
+                SocketAddr::V6(_) => None,
+            })
+            .next()
+            .unwrap()
+    }
+
+    #[test]
+    #[ignore]
+    fn google() {
+        let mut socket = Socks4Stream::connect("127.0.0.1:1080", google_ip(), "").unwrap();
+
+        socket.write_all(b"GET / HTTP/1.0\r\n\r\n").unwrap();
+        let mut result = vec![];
+        socket.read_to_end(&mut result).unwrap();
+
+        println!("{}", String::from_utf8_lossy(&result));
+        assert!(result.starts_with(b"HTTP/1.0"));
+        assert!(result.ends_with(b"</HTML>\r\n") || result.ends_with(b"</html>"));
+    }
+
+    #[test]
+    #[ignore] // dante doesn't support SOCKS4A
+    fn google_dns() {
+        let mut socket = Socks4Stream::connect("127.0.0.1:8080", "google.com:80", "").unwrap();
+
+        socket.write_all(b"GET / HTTP/1.0\r\n\r\n").unwrap();
+        let mut result = vec![];
+        socket.read_to_end(&mut result).unwrap();
+
+        println!("{}", String::from_utf8_lossy(&result));
+        assert!(result.starts_with(b"HTTP/1.0"));
+        assert!(result.ends_with(b"</HTML>\r\n") || result.ends_with(b"</html>"));
+    }
+
+    #[test]
+    #[ignore]
+    fn bind() {
+        // First figure out our local address that we'll be connecting from
+        let socket = Socks4Stream::connect("127.0.0.1:1080", google_ip(), "").unwrap();
+        let addr = socket.proxy_addr();
+
+        let listener = Socks4Listener::bind("127.0.0.1:1080", addr, "").unwrap();
+        let addr = listener.proxy_addr().unwrap();
+        let mut end = TcpStream::connect(addr).unwrap();
+        let mut conn = listener.accept().unwrap();
+        conn.write_all(b"hello world").unwrap();
+        drop(conn);
+        let mut result = vec![];
+        end.read_to_end(&mut result).unwrap();
+        assert_eq!(result, b"hello world");
+    }
+}

src/socks/v5.rs

@@ -0,0 +1,798 @@
+use byteorder::{BigEndian, ReadBytesExt, WriteBytesExt};
+use std::cmp;
+use std::io::{self, Read, Write};
+use std::net::{
+    Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6, TcpStream, ToSocketAddrs, UdpSocket,
+};
+use std::ptr;
+use std::time::Duration;
+
+use super::writev::WritevExt;
+use super::{TargetAddr, ToTargetAddr};
+
+const MAX_ADDR_LEN: usize = 260;
+
+fn read_addr<R: Read>(socket: &mut R) -> io::Result<TargetAddr> {
+    match socket.read_u8()? {
+        1 => {
+            let ip = Ipv4Addr::from(socket.read_u32::<BigEndian>()?);
+            let port = socket.read_u16::<BigEndian>()?;
+            Ok(TargetAddr::Ip(SocketAddr::V4(SocketAddrV4::new(ip, port))))
+        }
+        3 => {
+            let len = socket.read_u8()?;
+            let mut domain = vec![0; len as usize];
+            socket.read_exact(&mut domain)?;
+            let domain = String::from_utf8(domain)
+                .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
+            let port = socket.read_u16::<BigEndian>()?;
+            Ok(TargetAddr::Domain(domain, port))
+        }
+        4 => {
+            let mut ip = [0; 16];
+            socket.read_exact(&mut ip)?;
+            let ip = Ipv6Addr::from(ip);
+            let port = socket.read_u16::<BigEndian>()?;
+            Ok(TargetAddr::Ip(SocketAddr::V6(SocketAddrV6::new(
+                ip, port, 0, 0,
+            ))))
+        }
+        _ => Err(io::Error::other("unsupported address type")),
+    }
+}
+
+fn read_response(socket: &mut TcpStream) -> io::Result<TargetAddr> {
+    if socket.read_u8()? != 5 {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            "invalid response version",
+        ));
+    }
+
+    match socket.read_u8()? {
+        0 => {}
+        1 => return Err(io::Error::other("general SOCKS server failure")),
+        2 => return Err(io::Error::other("connection not allowed by ruleset")),
+        3 => return Err(io::Error::other("network unreachable")),
+        4 => return Err(io::Error::other("host unreachable")),
+        5 => return Err(io::Error::other("connection refused")),
+        6 => return Err(io::Error::other("TTL expired")),
+        7 => return Err(io::Error::other("command not supported")),
+        8 => return Err(io::Error::other("address kind not supported")),
+        _ => return Err(io::Error::other("unknown error")),
+    }
+
+    if socket.read_u8()? != 0 {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            "invalid reserved byte",
+        ));
+    }
+
+    read_addr(socket)
+}
+
+fn write_addr(mut packet: &mut [u8], target: &TargetAddr) -> io::Result<usize> {
+    let start_len = packet.len();
+    match *target {
+        TargetAddr::Ip(SocketAddr::V4(addr)) => {
+            packet.write_u8(1).unwrap();
+            packet.write_u32::<BigEndian>((*addr.ip()).into()).unwrap();
+            packet.write_u16::<BigEndian>(addr.port()).unwrap();
+        }
+        TargetAddr::Ip(SocketAddr::V6(addr)) => {
+            packet.write_u8(4).unwrap();
+            packet.write_all(&addr.ip().octets()).unwrap();
+            packet.write_u16::<BigEndian>(addr.port()).unwrap();
+        }
+        TargetAddr::Domain(ref domain, port) => {
+            packet.write_u8(3).unwrap();
+            if domain.len() > u8::MAX as usize {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "domain name too long",
+                ));
+            }
+            packet.write_u8(domain.len() as u8).unwrap();
+            packet.write_all(domain.as_bytes()).unwrap();
+            packet.write_u16::<BigEndian>(port).unwrap();
+        }
+    }
+
+    Ok(start_len - packet.len())
+}
+
+/// Authentication methods
+#[derive(Debug)]
+enum Authentication<'a> {
+    Password {
+        username: &'a str,
+        password: &'a str,
+    },
+    None,
+}
+
+impl Authentication<'_> {
+    fn id(&self) -> u8 {
+        match *self {
+            Authentication::Password { .. } => 2,
+            Authentication::None => 0,
+        }
+    }
+
+    fn is_no_auth(&self) -> bool {
+        matches!(*self, Authentication::None)
+    }
+}
+
+/// A SOCKS5 client.
+#[derive(Debug)]
+pub struct Socks5Stream {
+    socket: TcpStream,
+    proxy_addr: TargetAddr,
+}
+
+impl Socks5Stream {
+    /// Connects to a target server through a SOCKS5 proxy.
+    pub fn connect<T, U>(proxy: T, target: U, timeout: Option<Duration>) -> io::Result<Socks5Stream>
+    where
+        T: ToSocketAddrs,
+        U: ToTargetAddr,
+    {
+        Self::connect_raw(1, proxy, target, &Authentication::None, timeout)
+    }
+
+    /// Connects to a target server through a SOCKS5 proxy using given
+    /// username and password.
+    pub fn connect_with_password<T, U>(
+        proxy: T,
+        target: U,
+        username: &str,
+        password: &str,
+        timeout: Option<Duration>,
+    ) -> io::Result<Socks5Stream>
+    where
+        T: ToSocketAddrs,
+        U: ToTargetAddr,
+    {
+        let auth = Authentication::Password { username, password };
+        Self::connect_raw(1, proxy, target, &auth, timeout)
+    }
+
+    fn connect_raw<T, U>(
+        command: u8,
+        proxy: T,
+        target: U,
+        auth: &Authentication,
+        timeout: Option<Duration>,
+    ) -> io::Result<Socks5Stream>
+    where
+        T: ToSocketAddrs,
+        U: ToTargetAddr,
+    {
+        let mut socket = if let Some(timeout) = timeout {
+            let addr = proxy.to_socket_addrs()?.next().unwrap();
+            TcpStream::connect_timeout(&addr, timeout)?
+        } else {
+            TcpStream::connect(proxy)?
+        };
+
+        socket.set_read_timeout(timeout)?;
+        socket.set_write_timeout(timeout)?;
+
+        let target = target.to_target_addr()?;
+
+        let packet_len = if auth.is_no_auth() { 3 } else { 4 };
+        let packet = [
+            5,                                     // protocol version
+            if auth.is_no_auth() { 1 } else { 2 }, // method count
+            auth.id(),                             // method
+            0,                                     // no auth (always offered)
+        ];
+        socket.write_all(&packet[..packet_len])?;
+
+        let mut buf = [0; 2];
+        socket.read_exact(&mut buf)?;
+        let response_version = buf[0];
+        let selected_method = buf[1];
+
+        if response_version != 5 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "invalid response version",
+            ));
+        }
+
+        if selected_method == 0xff {
+            return Err(io::Error::other("no acceptable auth methods"));
+        }
+
+        if selected_method != auth.id() && selected_method != Authentication::None.id() {
+            return Err(io::Error::other("unknown auth method"));
+        }
+
+        match *auth {
+            Authentication::Password { username, password } if selected_method == auth.id() => {
+                Self::password_authentication(&mut socket, username, password)?
+            }
+            _ => (),
+        }
+
+        let mut packet = [0; MAX_ADDR_LEN + 3];
+        packet[0] = 5; // protocol version
+        packet[1] = command; // command
+        packet[2] = 0; // reserved
+        let len = write_addr(&mut packet[3..], &target)?;
+        socket.write_all(&packet[..len + 3])?;
+
+        let proxy_addr = read_response(&mut socket)?;
+
+        Ok(Socks5Stream { socket, proxy_addr })
+    }
+
+    fn password_authentication(
+        socket: &mut TcpStream,
+        username: &str,
+        password: &str,
+    ) -> io::Result<()> {
+        if username.is_empty() || username.len() > 255 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "invalid username",
+            ));
+        };
+        if password.is_empty() || password.len() > 255 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "invalid password",
+            ));
+        }
+
+        let mut packet = [0; 515];
+        let packet_size = 3 + username.len() + password.len();
+        packet[0] = 1; // version
+        packet[1] = username.len() as u8;
+        packet[2..2 + username.len()].copy_from_slice(username.as_bytes());
+        packet[2 + username.len()] = password.len() as u8;
+        packet[3 + username.len()..packet_size].copy_from_slice(password.as_bytes());
+        socket.write_all(&packet[..packet_size])?;
+
+        let mut buf = [0; 2];
+        socket.read_exact(&mut buf)?;
+        if buf[0] != 1 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "invalid response version",
+            ));
+        }
+        if buf[1] != 0 {
+            return Err(io::Error::new(
+                io::ErrorKind::PermissionDenied,
+                "password authentication failed",
+            ));
+        }
+
+        Ok(())
+    }
+
+    /// Returns the proxy-side address of the connection between the proxy and
+    /// target server.
+    pub fn proxy_addr(&self) -> &TargetAddr {
+        &self.proxy_addr
+    }
+
+    /// Returns a shared reference to the inner `TcpStream`.
+    pub fn get_ref(&self) -> &TcpStream {
+        &self.socket
+    }
+
+    /// Returns a mutable reference to the inner `TcpStream`.
+    pub fn get_mut(&mut self) -> &mut TcpStream {
+        &mut self.socket
+    }
+
+    /// Consumes the `Socks5Stream`, returning the inner `TcpStream`.
+    pub fn into_inner(self) -> TcpStream {
+        self.socket
+    }
+}
+
+impl Read for Socks5Stream {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        self.socket.read(buf)
+    }
+}
+
+impl Read for &Socks5Stream {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        (&self.socket).read(buf)
+    }
+}
+
+impl Write for Socks5Stream {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        self.socket.write(buf)
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        self.socket.flush()
+    }
+}
+
+impl Write for &Socks5Stream {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        (&self.socket).write(buf)
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        (&self.socket).flush()
+    }
+}
+
+/// A SOCKS5 BIND client.
+#[derive(Debug)]
+pub struct Socks5Listener(Socks5Stream);
+
+impl Socks5Listener {
+    /// Initiates a BIND request to the specified proxy.
+    ///
+    /// The proxy will filter incoming connections based on the value of
+    /// `target`.
+    pub fn bind<T, U>(proxy: T, target: U, timeout: Option<Duration>) -> io::Result<Socks5Listener>
+    where
+        T: ToSocketAddrs,
+        U: ToTargetAddr,
+    {
+        Socks5Stream::connect_raw(2, proxy, target, &Authentication::None, timeout)
+            .map(Socks5Listener)
+    }
+    /// Initiates a BIND request to the specified proxy using given username
+    /// and password.
+    ///
+    /// The proxy will filter incoming connections based on the value of
+    /// `target`.
+    pub fn bind_with_password<T, U>(
+        proxy: T,
+        target: U,
+        username: &str,
+        password: &str,
+        timeout: Option<Duration>,
+    ) -> io::Result<Socks5Listener>
+    where
+        T: ToSocketAddrs,
+        U: ToTargetAddr,
+    {
+        let auth = Authentication::Password { username, password };
+        Socks5Stream::connect_raw(2, proxy, target, &auth, timeout).map(Socks5Listener)
+    }
+
+    /// The address of the proxy-side TCP listener.
+    ///
+    /// This should be forwarded to the remote process, which should open a
+    /// connection to it.
+    pub fn proxy_addr(&self) -> &TargetAddr {
+        &self.0.proxy_addr
+    }
+
+    /// Waits for the remote process to connect to the proxy server.
+    ///
+    /// The value of `proxy_addr` should be forwarded to the remote process
+    /// before this method is called.
+    pub fn accept(mut self) -> io::Result<Socks5Stream> {
+        self.0.proxy_addr = read_response(&mut self.0.socket)?;
+        Ok(self.0)
+    }
+}
+
+/// A SOCKS5 UDP client.
+#[derive(Debug)]
+pub struct Socks5Datagram {
+    socket: UdpSocket,
+    // keeps the session alive
+    stream: Socks5Stream,
+}
+
+impl Socks5Datagram {
+    /// Creates a UDP socket bound to the specified address which will have its
+    /// traffic routed through the specified proxy.
+    pub fn bind<T, U>(proxy: T, addr: U, timeout: Option<Duration>) -> io::Result<Socks5Datagram>
+    where
+        T: ToSocketAddrs,
+        U: ToSocketAddrs,
+    {
+        Self::bind_internal(proxy, addr, &Authentication::None, timeout)
+    }
+    /// Creates a UDP socket bound to the specified address which will have its
+    /// traffic routed through the specified proxy. The given username and password
+    /// is used to authenticate to the SOCKS proxy.
+    pub fn bind_with_password<T, U>(
+        proxy: T,
+        addr: U,
+        username: &str,
+        password: &str,
+        timeout: Option<Duration>,
+    ) -> io::Result<Socks5Datagram>
+    where
+        T: ToSocketAddrs,
+        U: ToSocketAddrs,
+    {
+        let auth = Authentication::Password { username, password };
+        Self::bind_internal(proxy, addr, &auth, timeout)
+    }
+
+    fn bind_internal<T, U>(
+        proxy: T,
+        addr: U,
+        auth: &Authentication,
+        timeout: Option<Duration>,
+    ) -> io::Result<Socks5Datagram>
+    where
+        T: ToSocketAddrs,
+        U: ToSocketAddrs,
+    {
+        // we don't know what our IP is from the perspective of the proxy, so
+        // don't try to pass `addr` in here.
+        let dst = TargetAddr::Ip(SocketAddr::V4(SocketAddrV4::new(
+            Ipv4Addr::new(0, 0, 0, 0),
+            0,
+        )));
+        let stream = Socks5Stream::connect_raw(3, proxy, dst, auth, timeout)?;
+
+        let socket = UdpSocket::bind(addr)?;
+        socket.connect(&stream.proxy_addr)?;
+
+        Ok(Socks5Datagram { socket, stream })
+    }
+
+    /// Like `UdpSocket::send_to`.
+    ///
+    /// # Note
+    ///
+    /// The SOCKS protocol inserts a header at the beginning of the message. The
+    /// header will be 10 bytes for an IPv4 address, 22 bytes for an IPv6
+    /// address, and 7 bytes plus the length of the domain for a domain address.
+    pub fn send_to<A>(&self, buf: &[u8], addr: A) -> io::Result<usize>
+    where
+        A: ToTargetAddr,
+    {
+        let addr = addr.to_target_addr()?;
+
+        let mut header = [0; MAX_ADDR_LEN + 3];
+        // first two bytes are reserved at 0
+        // third byte is the fragment id at 0
+        let len = write_addr(&mut header[3..], &addr)?;
+
+        self.socket.writev([&header[..len + 3], buf])
+    }
+
+    /// Like `UdpSocket::recv_from`.
+    pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, TargetAddr)> {
+        let mut header = [0; MAX_ADDR_LEN + 3];
+        let len = self.socket.readv([&mut header, buf])?;
+
+        let overflow = len.saturating_sub(header.len());
+
+        let header_len = cmp::min(header.len(), len);
+        let mut header = &mut &header[..header_len];
+
+        if header.read_u16::<BigEndian>()? != 0 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "invalid reserved bytes",
+            ));
+        }
+        if header.read_u8()? != 0 {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "invalid fragment id",
+            ));
+        }
+        let addr = read_addr(&mut header)?;
+
+        unsafe {
+            ptr::copy(buf.as_ptr(), buf.as_mut_ptr().add(header.len()), overflow);
+        }
+        buf[..header.len()].copy_from_slice(header);
+
+        Ok((header.len() + overflow, addr))
+    }
+
+    /// Returns the address of the proxy-side UDP socket through which all
+    /// messages will be routed.
+    pub fn proxy_addr(&self) -> &TargetAddr {
+        &self.stream.proxy_addr
+    }
+
+    /// Returns a shared reference to the inner socket.
+    pub fn get_ref(&self) -> &UdpSocket {
+        &self.socket
+    }
+
+    /// Returns a mutable reference to the inner socket.
+    pub fn get_mut(&mut self) -> &mut UdpSocket {
+        &mut self.socket
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use std::io::{Read, Write};
+    use std::net::{TcpStream, ToSocketAddrs, UdpSocket};
+
+    use super::*;
+
+    const SOCKS_PROXY_NO_AUTH_ONLY: &str = "127.0.0.1:1080";
+    const SOCKS_PROXY_PASSWD_ONLY: &str = "127.0.0.1:1081";
+
+    #[test]
+    #[ignore]
+    fn google_no_auth() {
+        let addr = "google.com:80".to_socket_addrs().unwrap().next().unwrap();
+        let socket = Socks5Stream::connect(SOCKS_PROXY_NO_AUTH_ONLY, addr, None).unwrap();
+        google(socket);
+    }
+
+    #[test]
+    #[ignore]
+    fn google_with_password() {
+        let addr = "google.com:80".to_socket_addrs().unwrap().next().unwrap();
+        let socket = Socks5Stream::connect_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            addr,
+            "testuser",
+            "testpass",
+            None,
+        )
+        .unwrap();
+        google(socket);
+    }
+
+    fn google(mut socket: Socks5Stream) {
+        socket.write_all(b"GET / HTTP/1.0\r\n\r\n").unwrap();
+        let mut result = vec![];
+        socket.read_to_end(&mut result).unwrap();
+
+        println!("{}", String::from_utf8_lossy(&result));
+        assert!(result.starts_with(b"HTTP/1.0"));
+        assert!(result.ends_with(b"</HTML>\r\n") || result.ends_with(b"</html>"));
+    }
+
+    #[test]
+    #[ignore]
+    fn google_dns() {
+        let mut socket =
+            Socks5Stream::connect(SOCKS_PROXY_NO_AUTH_ONLY, "google.com:80", None).unwrap();
+
+        socket.write_all(b"GET / HTTP/1.0\r\n\r\n").unwrap();
+        let mut result = vec![];
+        socket.read_to_end(&mut result).unwrap();
+
+        println!("{}", String::from_utf8_lossy(&result));
+        assert!(result.starts_with(b"HTTP/1.0"));
+        assert!(result.ends_with(b"</HTML>\r\n") || result.ends_with(b"</html>"));
+    }
+
+    #[test]
+    #[ignore]
+    fn bind_no_auth() {
+        let addr = find_address();
+        let listener = Socks5Listener::bind(SOCKS_PROXY_NO_AUTH_ONLY, addr, None).unwrap();
+        bind(listener);
+    }
+
+    #[test]
+    #[ignore]
+    fn bind_with_password_supported_but_no_auth_used() {
+        let addr = find_address();
+        let listener = Socks5Listener::bind_with_password(
+            SOCKS_PROXY_NO_AUTH_ONLY,
+            addr,
+            "unused_and_invalid_username",
+            "unused_and_invalid_password",
+            None,
+        )
+        .unwrap();
+        bind(listener);
+    }
+
+    #[test]
+    #[ignore]
+    fn bind_with_password() {
+        let addr = find_address();
+        let listener = Socks5Listener::bind_with_password(
+            "127.0.0.1:1081",
+            addr,
+            "testuser",
+            "testpass",
+            None,
+        )
+        .unwrap();
+        bind(listener);
+    }
+
+    fn bind(listener: Socks5Listener) {
+        let addr = listener.proxy_addr().clone();
+        let mut end = TcpStream::connect(addr).unwrap();
+        let mut conn = listener.accept().unwrap();
+        conn.write_all(b"hello world").unwrap();
+        drop(conn);
+        let mut result = vec![];
+        end.read_to_end(&mut result).unwrap();
+        assert_eq!(result, b"hello world");
+    }
+
+    // First figure out our local address that we'll be connecting from
+    fn find_address() -> TargetAddr {
+        let socket =
+            Socks5Stream::connect(SOCKS_PROXY_NO_AUTH_ONLY, "google.com:80", None).unwrap();
+        socket.proxy_addr().to_owned()
+    }
+
+    #[test]
+    #[ignore]
+    fn associate_no_auth() {
+        let socks =
+            Socks5Datagram::bind(SOCKS_PROXY_NO_AUTH_ONLY, "127.0.0.1:15410", None).unwrap();
+        associate(socks, "127.0.0.1:15411");
+    }
+
+    #[test]
+    #[ignore]
+    fn associate_with_password() {
+        let socks = Socks5Datagram::bind_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            "127.0.0.1:15414",
+            "testuser",
+            "testpass",
+            None,
+        )
+        .unwrap();
+        associate(socks, "127.0.0.1:15415");
+    }
+
+    fn associate(socks: Socks5Datagram, socket_addr: &str) {
+        let socket = UdpSocket::bind(socket_addr).unwrap();
+
+        socks.send_to(b"hello world!", socket_addr).unwrap();
+        let mut buf = [0; 13];
+        let (len, addr) = socket.recv_from(&mut buf).unwrap();
+        assert_eq!(len, 12);
+        assert_eq!(&buf[..12], b"hello world!");
+
+        socket.send_to(b"hello world!", addr).unwrap();
+
+        let len = socks.recv_from(&mut buf).unwrap().0;
+        assert_eq!(len, 12);
+        assert_eq!(&buf[..12], b"hello world!");
+    }
+
+    #[test]
+    #[ignore]
+    fn associate_long() {
+        let socks =
+            Socks5Datagram::bind(SOCKS_PROXY_NO_AUTH_ONLY, "127.0.0.1:15412", None).unwrap();
+        let socket_addr = "127.0.0.1:15413";
+        let socket = UdpSocket::bind(socket_addr).unwrap();
+
+        let mut msg = vec![];
+        for i in 0..(MAX_ADDR_LEN + 100) {
+            msg.push(i as u8);
+        }
+
+        socks.send_to(&msg, socket_addr).unwrap();
+        let mut buf = vec![0; msg.len() + 1];
+        let (len, addr) = socket.recv_from(&mut buf).unwrap();
+        assert_eq!(len, msg.len());
+        assert_eq!(msg, &buf[..msg.len()]);
+
+        socket.send_to(&msg, addr).unwrap();
+
+        let mut buf = vec![0; msg.len() + 1];
+        let len = socks.recv_from(&mut buf).unwrap().0;
+        assert_eq!(len, msg.len());
+        assert_eq!(msg, &buf[..msg.len()]);
+    }
+
+    #[test]
+    #[ignore]
+    fn incorrect_password() {
+        let addr = "google.com:80".to_socket_addrs().unwrap().next().unwrap();
+        let err = Socks5Stream::connect_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            addr,
+            "testuser",
+            "invalid",
+            None,
+        )
+        .unwrap_err();
+
+        assert_eq!(err.kind(), io::ErrorKind::PermissionDenied);
+        assert_eq!(err.to_string(), "password authentication failed");
+    }
+
+    #[test]
+    #[ignore]
+    fn auth_method_not_supported() {
+        let addr = "google.com:80".to_socket_addrs().unwrap().next().unwrap();
+        let err = Socks5Stream::connect(SOCKS_PROXY_PASSWD_ONLY, addr, None).unwrap_err();
+
+        assert_eq!(err.kind(), io::ErrorKind::Other);
+        assert_eq!(err.to_string(), "no acceptable auth methods");
+    }
+
+    #[test]
+    #[ignore]
+    fn username_and_password_length() {
+        let addr = "google.com:80".to_socket_addrs().unwrap().next().unwrap();
+
+        let err = Socks5Stream::connect_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            addr,
+            &string_of_size(1),
+            &string_of_size(1),
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err.kind(), io::ErrorKind::PermissionDenied);
+        assert_eq!(err.to_string(), "password authentication failed");
+
+        let err = Socks5Stream::connect_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            addr,
+            &string_of_size(255),
+            &string_of_size(255),
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err.kind(), io::ErrorKind::PermissionDenied);
+        assert_eq!(err.to_string(), "password authentication failed");
+
+        let err = Socks5Stream::connect_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            addr,
+            &string_of_size(0),
+            &string_of_size(255),
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
+        assert_eq!(err.to_string(), "invalid username");
+
+        let err = Socks5Stream::connect_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            addr,
+            &string_of_size(256),
+            &string_of_size(255),
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
+        assert_eq!(err.to_string(), "invalid username");
+
+        let err = Socks5Stream::connect_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            addr,
+            &string_of_size(255),
+            &string_of_size(0),
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
+        assert_eq!(err.to_string(), "invalid password");
+
+        let err = Socks5Stream::connect_with_password(
+            SOCKS_PROXY_PASSWD_ONLY,
+            addr,
+            &string_of_size(255),
+            &string_of_size(256),
+            None,
+        )
+        .unwrap_err();
+        assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
+        assert_eq!(err.to_string(), "invalid password");
+    }
+
+    fn string_of_size(size: usize) -> String {
+        (0..size).map(|_| 'x').collect()
+    }
+}

src/socks/writev.rs

@@ -0,0 +1,133 @@
+use std::io;
+use std::net::UdpSocket;
+
+pub trait WritevExt {
+    fn writev(&self, bufs: [&[u8]; 2]) -> io::Result<usize>;
+    fn readv(&self, bufs: [&mut [u8]; 2]) -> io::Result<usize>;
+}
+
+#[cfg(unix)]
+mod imp {
+    use libc;
+    use std::os::unix::io::AsRawFd;
+
+    use super::*;
+
+    impl WritevExt for UdpSocket {
+        fn writev(&self, bufs: [&[u8]; 2]) -> io::Result<usize> {
+            unsafe {
+                let iovecs = [
+                    libc::iovec {
+                        iov_base: bufs[0].as_ptr() as *const _ as *mut _,
+                        iov_len: bufs[0].len(),
+                    },
+                    libc::iovec {
+                        iov_base: bufs[1].as_ptr() as *const _ as *mut _,
+                        iov_len: bufs[1].len(),
+                    },
+                ];
+                let r = libc::writev(self.as_raw_fd(), iovecs.as_ptr(), 2);
+                if r < 0 {
+                    Err(io::Error::last_os_error())
+                } else {
+                    Ok(r as usize)
+                }
+            }
+        }
+
+        fn readv(&self, bufs: [&mut [u8]; 2]) -> io::Result<usize> {
+            unsafe {
+                let mut iovecs = [
+                    libc::iovec {
+                        iov_base: bufs[0].as_mut_ptr() as *mut _,
+                        iov_len: bufs[0].len(),
+                    },
+                    libc::iovec {
+                        iov_base: bufs[1].as_mut_ptr() as *mut _,
+                        iov_len: bufs[1].len(),
+                    },
+                ];
+                let r = libc::readv(self.as_raw_fd(), iovecs.as_mut_ptr(), 2);
+                if r < 0 {
+                    Err(io::Error::last_os_error())
+                } else {
+                    Ok(r as usize)
+                }
+            }
+        }
+    }
+}
+
+#[cfg(windows)]
+mod imp {
+    use std::os::windows::io::AsRawSocket;
+    use std::ptr;
+    use winapi::shared::minwindef;
+    use winapi::shared::ws2def;
+    use winapi::um::winsock2;
+
+    use super::*;
+
+    impl WritevExt for UdpSocket {
+        fn writev(&self, bufs: [&[u8]; 2]) -> io::Result<usize> {
+            unsafe {
+                let mut wsabufs = [
+                    ws2def::WSABUF {
+                        len: bufs[0].len() as winsock2::u_long,
+                        buf: bufs[0].as_ptr() as *const _ as *mut _,
+                    },
+                    ws2def::WSABUF {
+                        len: bufs[1].len() as winsock2::u_long,
+                        buf: bufs[1].as_ptr() as *const _ as *mut _,
+                    },
+                ];
+                let mut sent = 0;
+                let r = winsock2::WSASend(
+                    self.as_raw_socket() as usize,
+                    wsabufs.as_mut_ptr(),
+                    bufs.len() as minwindef::DWORD,
+                    &mut sent,
+                    0,
+                    ptr::null_mut(),
+                    None,
+                );
+                if r == 0 {
+                    Ok(sent as usize)
+                } else {
+                    Err(io::Error::last_os_error())
+                }
+            }
+        }
+
+        fn readv(&self, bufs: [&mut [u8]; 2]) -> io::Result<usize> {
+            unsafe {
+                let mut wsabufs = [
+                    ws2def::WSABUF {
+                        len: bufs[0].len() as winsock2::u_long,
+                        buf: bufs[0].as_mut_ptr() as *mut _,
+                    },
+                    ws2def::WSABUF {
+                        len: bufs[1].len() as winsock2::u_long,
+                        buf: bufs[1].as_mut_ptr() as *mut _,
+                    },
+                ];
+                let mut recved = 0;
+                let mut flags = 0;
+                let r = winsock2::WSARecv(
+                    self.as_raw_socket() as usize,
+                    wsabufs.as_mut_ptr(),
+                    bufs.len() as minwindef::DWORD,
+                    &mut recved,
+                    &mut flags,
+                    ptr::null_mut(),
+                    None,
+                );
+                if r == 0 {
+                    Ok(recved as usize)
+                } else {
+                    Err(io::Error::last_os_error())
+                }
+            }
+        }
+    }
+}

src/stream.rs

@@ -1,3 +1,4 @@
+use log::error;
 use std::io::{self, Read, Write};
 use std::sync::{Arc, Mutex};
 
@@ -6,17 +7,35 @@ pub struct ClonableStream<T: Read + Write>(Arc<Mutex<T>>);
 
 impl<T: Read + Write> Read for ClonableStream<T> {
     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
-        self.0.lock().unwrap().read(buf)
+        self.0
+            .lock()
+            .map_err(|_| {
+                error!("Unable to acquire lock on ClonableStream read operation");
+                io::Error::from(io::ErrorKind::BrokenPipe)
+            })?
+            .read(buf)
     }
 }
 
 impl<T: Read + Write> Write for ClonableStream<T> {
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
-        self.0.lock().unwrap().write(buf)
+        self.0
+            .lock()
+            .map_err(|_| {
+                error!("Unable to acquire lock on ClonableStream write operation");
+                io::Error::from(io::ErrorKind::BrokenPipe)
+            })?
+            .write(buf)
     }
 
     fn flush(&mut self) -> io::Result<()> {
-        self.0.lock().unwrap().flush()
+        self.0
+            .lock()
+            .map_err(|_| {
+                error!("Unable to acquire lock on ClonableStream flush operation");
+                io::Error::from(io::ErrorKind::BrokenPipe)
+            })?
+            .flush()
     }
 }
 

src/types.rs

@@ -3,18 +3,22 @@
 //! This module contains definitions of all the complex data structures that are returned by calls
 
 use std::convert::TryFrom;
+use std::fmt::{self, Display, Formatter};
 use std::ops::Deref;
+use std::sync::Arc;
 
 use bitcoin::blockdata::block;
 use bitcoin::consensus::encode::deserialize;
-use bitcoin::hashes::hex::FromHex;
 use bitcoin::hashes::{sha256, Hash};
+use bitcoin::hex::{DisplayHex, FromHex};
 use bitcoin::{Script, Txid};
 
 use serde::{de, Deserialize, Serialize};
 
 static JSONRPC_2_0: &str = "2.0";
 
+pub(crate) type Call = (String, Vec<Param>);
+
 #[derive(Serialize, Clone)]
 #[serde(untagged)]
 /// A single parameter of a [`Request`](struct.Request.html)
@@ -65,8 +69,8 @@ impl<'a> Request<'a> {
 }
 
 #[doc(hidden)]
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize, Serialize)]
-pub struct Hex32Bytes(#[serde(deserialize_with = "from_hex")] [u8; 32]);
+pub struct Hex32Bytes(#[serde(deserialize_with = "from_hex", serialize_with = "to_hex")] [u8; 32]);
 
 impl Deref for Hex32Bytes {
     type Target = [u8; 32];
@@ -82,6 +86,12 @@ impl From<[u8; 32]> for Hex32Bytes {
     }
 }
 
+impl Hex32Bytes {
+    pub(crate) fn to_hex(self) -> String {
+        self.0.to_lower_hex_string()
+    }
+}
+
 /// Format used by the Electrum server to identify an address. The reverse sha256 hash of the
 /// scriptPubKey. Documented [here](https://electrumx.readthedocs.io/en/latest/protocol-basics.html#script-hashes).
 pub type ScriptHash = Hex32Bytes;
@@ -98,7 +108,7 @@ pub trait ToElectrumScriptHash {
 
 impl ToElectrumScriptHash for Script {
     fn to_electrum_scripthash(&self) -> ScriptHash {
-        let mut result = sha256::Hash::hash(self.as_bytes()).into_inner();
+        let mut result = sha256::Hash::hash(self.as_bytes()).to_byte_array();
         result.reverse();
 
         result.into()
@@ -114,6 +124,13 @@ where
     T::from_hex(&s).map_err(de::Error::custom)
 }
 
+fn to_hex<S>(bytes: &[u8], serializer: S) -> std::result::Result<S::Ok, S::Error>
+where
+    S: serde::ser::Serializer,
+{
+    serializer.serialize_str(&bytes.to_lower_hex_string())
+}
+
 fn from_hex_array<'de, T, D>(deserializer: D) -> Result<Vec<T>, D::Error>
 where
     T: FromHex + std::fmt::Debug,
@@ -134,7 +151,7 @@ where
     Ok(answer)
 }
 
-fn from_hex_header<'de, D>(deserializer: D) -> Result<block::BlockHeader, D::Error>
+fn from_hex_header<'de, D>(deserializer: D) -> Result<block::Header, D::Error>
 where
     D: de::Deserializer<'de>,
 {
@@ -143,7 +160,7 @@ where
 }
 
 /// Response to a [`script_get_history`](../client/struct.Client.html#method.script_get_history) request.
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct GetHistoryRes {
     /// Confirmation height of the transaction. 0 if unconfirmed, -1 if unconfirmed while some of
     /// its inputs are unconfirmed too.
@@ -155,7 +172,7 @@ pub struct GetHistoryRes {
 }
 
 /// Response to a [`script_list_unspent`](../client/struct.Client.html#method.script_list_unspent) request.
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct ListUnspentRes {
     /// Confirmation height of the transaction that created this output.
     pub height: usize,
@@ -168,7 +185,7 @@ pub struct ListUnspentRes {
 }
 
 /// Response to a [`server_features`](../client/struct.Client.html#method.server_features) request.
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct ServerFeaturesRes {
     /// Server version reported.
     pub server_version: String,
@@ -186,7 +203,7 @@ pub struct ServerFeaturesRes {
 }
 
 /// Response to a [`server_features`](../client/struct.Client.html#method.server_features) request.
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct GetHeadersRes {
     /// Maximum number of headers returned in a single response.
     pub max: usize,
@@ -197,20 +214,22 @@ pub struct GetHeadersRes {
     pub raw_headers: Vec<u8>,
     /// Array of block headers.
     #[serde(skip)]
-    pub headers: Vec<block::BlockHeader>,
+    pub headers: Vec<block::Header>,
 }
 
 /// Response to a [`script_get_balance`](../client/struct.Client.html#method.script_get_balance) request.
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct GetBalanceRes {
     /// Confirmed balance in Satoshis for the address.
     pub confirmed: u64,
     /// Unconfirmed balance in Satoshis for the address.
-    pub unconfirmed: u64,
+    ///
+    /// Some servers (e.g. `electrs`) return this as a negative value.
+    pub unconfirmed: i64,
 }
 
 /// Response to a [`transaction_get_merkle`](../client/struct.Client.html#method.transaction_get_merkle) request.
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct GetMerkleRes {
     /// Height of the block that confirmed the transaction
     pub block_height: usize,
@@ -221,18 +240,29 @@ pub struct GetMerkleRes {
     pub merkle: Vec<[u8; 32]>,
 }
 
+/// Response to a [`txid_from_pos_with_merkle`](../client/struct.Client.html#method.txid_from_pos_with_merkle)
+/// request.
+#[derive(Clone, Debug, Deserialize)]
+pub struct TxidFromPosRes {
+    /// Txid of the transaction.
+    pub tx_hash: Txid,
+    /// The merkle path of the transaction.
+    #[serde(deserialize_with = "from_hex_array")]
+    pub merkle: Vec<[u8; 32]>,
+}
+
 /// Notification of a new block header
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct HeaderNotification {
     /// New block height.
     pub height: usize,
     /// Newly added header.
     #[serde(rename = "hex", deserialize_with = "from_hex_header")]
-    pub header: block::BlockHeader,
+    pub header: block::Header,
 }
 
 /// Notification of a new block header with the header encoded as raw bytes
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct RawHeaderNotification {
     /// New block height.
     pub height: usize,
@@ -253,7 +283,7 @@ impl TryFrom<RawHeaderNotification> for HeaderNotification {
 }
 
 /// Notification of the new status of a script
-#[derive(Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize)]
 pub struct ScriptNotification {
     /// Address that generated this notification.
     pub scripthash: ScriptHash,
@@ -268,8 +298,8 @@ pub enum Error {
     IOError(std::io::Error),
     /// Wraps `serde_json::error::Error`
     JSON(serde_json::error::Error),
-    /// Wraps `bitcoin::hashes::hex::Error`
+    /// Wraps `bitcoin::hex::HexToBytesError`
-    Hex(bitcoin::hashes::hex::Error),
+    Hex(bitcoin::hex::HexToBytesError),
     /// Error returned by the Electrum server
     Protocol(serde_json::Value),
     /// Error during the deserialization of a Bitcoin data structure
@@ -286,12 +316,19 @@ pub enum Error {
     InvalidDNSNameError(String),
     /// Missing domain while it was explicitly asked to validate it
     MissingDomain,
-    /// SSL over a socks5 proxy is currently not supported
+    /// Made one or multiple attempts, always in Error
-    SSLOverSocks5,
+    AllAttemptsErrored(Vec<Error>),
+    /// There was an io error reading the socket, to be shared between threads
+    SharedIOError(Arc<std::io::Error>),
 
     /// Couldn't take a lock on the reader mutex. This means that there's already another reader
     /// thread running
     CouldntLockReader,
+    /// Broken IPC communication channel: the other thread probably has exited
+    Mpsc,
+    #[cfg(any(feature = "use-rustls", feature = "use-rustls-ring"))]
+    /// Could not create a rustls client connection
+    CouldNotCreateConnection(rustls::Error),
 
     #[cfg(feature = "use-openssl")]
     /// Invalid OpenSSL method used
@@ -301,11 +338,55 @@ pub enum Error {
     SslHandshakeError(openssl::ssl::HandshakeError<std::net::TcpStream>),
 }
 
+impl Display for Error {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            Error::IOError(e) => Display::fmt(e, f),
+            Error::JSON(e) => Display::fmt(e, f),
+            Error::Hex(e) => Display::fmt(e, f),
+            Error::Bitcoin(e) => Display::fmt(e, f),
+            Error::SharedIOError(e) => Display::fmt(e, f),
+            #[cfg(feature = "use-openssl")]
+            Error::SslHandshakeError(e) => Display::fmt(e, f),
+            #[cfg(feature = "use-openssl")]
+            Error::InvalidSslMethod(e) => Display::fmt(e, f),
+            #[cfg(any(
+                feature = "use-rustls",
+                feature = "use-rustls-ring",
+            ))]
+            Error::CouldNotCreateConnection(e) => Display::fmt(e, f),
+
+            Error::Message(e) => f.write_str(e),
+            Error::InvalidDNSNameError(domain) => write!(f, "Invalid domain name {} not matching SSL certificate", domain),
+            Error::AllAttemptsErrored(errors) => {
+                f.write_str("Made one or multiple attempts, all errored:\n")?;
+                for err in errors {
+                    writeln!(f, "\t- {}", err)?;
+                }
+                Ok(())
+            }
+
+            Error::Protocol(e) => write!(f, "Electrum server error: {}", e.clone().take()),
+            Error::InvalidResponse(e) => write!(f, "Error during the deserialization of a response from the server: {}", e.clone().take()),
+
+            // TODO: Print out addresses once `ScriptHash` will implement `Display`
+            Error::AlreadySubscribed(_) => write!(f, "Already subscribed to the notifications of an address"),
+            Error::NotSubscribed(_) => write!(f, "Not subscribed to the notifications of an address"),
+
+            Error::MissingDomain => f.write_str("Missing domain while it was explicitly asked to validate it"),
+            Error::CouldntLockReader => f.write_str("Couldn't take a lock on the reader mutex. This means that there's already another reader thread is running"),
+            Error::Mpsc => f.write_str("Broken IPC communication channel: the other thread probably has exited"),
+        }
+    }
+}
+
+impl std::error::Error for Error {}
+
 macro_rules! impl_error {
     ( $from:ty, $to:ident ) => {
         impl std::convert::From<$from> for Error {
             fn from(err: $from) -> Self {
-                Error::$to(err)
+                Error::$to(err.into())
             }
         }
     };
@@ -313,5 +394,36 @@ macro_rules! impl_error {
 
 impl_error!(std::io::Error, IOError);
 impl_error!(serde_json::Error, JSON);
-impl_error!(bitcoin::hashes::hex::Error, Hex);
+impl_error!(bitcoin::hex::HexToBytesError, Hex);
 impl_error!(bitcoin::consensus::encode::Error, Bitcoin);
+
+impl<T> From<std::sync::PoisonError<T>> for Error {
+    fn from(_: std::sync::PoisonError<T>) -> Self {
+        Error::IOError(std::io::Error::from(std::io::ErrorKind::BrokenPipe))
+    }
+}
+
+impl<T> From<std::sync::mpsc::SendError<T>> for Error {
+    fn from(_: std::sync::mpsc::SendError<T>) -> Self {
+        Error::Mpsc
+    }
+}
+
+impl From<std::sync::mpsc::RecvError> for Error {
+    fn from(_: std::sync::mpsc::RecvError) -> Self {
+        Error::Mpsc
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::ScriptStatus;
+
+    #[test]
+    fn script_status_roundtrip() {
+        let script_status: ScriptStatus = [1u8; 32].into();
+        let script_status_json = serde_json::to_string(&script_status).unwrap();
+        let script_status_back = serde_json::from_str(&script_status_json).unwrap();
+        assert_eq!(script_status, script_status_back);
+    }
+}

src/utils.rs

@@ -0,0 +1,43 @@
+//! Utilities helping to handle Electrum-related data.
+
+use crate::types::GetMerkleRes;
+use bitcoin::hash_types::TxMerkleNode;
+use bitcoin::hashes::sha256d::Hash as Sha256d;
+use bitcoin::hashes::{Hash, HashEngine};
+use bitcoin::Txid;
+
+/// Verifies a Merkle inclusion proof as retrieved via [`transaction_get_merkle`] for a transaction with the
+/// given `txid` and `merkle_root` as included in the [`BlockHeader`].
+///
+/// Returns `true` if the transaction is included in the corresponding block, and `false`
+/// otherwise.
+///
+/// [`transaction_get_merkle`]: crate::ElectrumApi::transaction_get_merkle
+/// [`BlockHeader`]: bitcoin::block::Header
+pub fn validate_merkle_proof(
+    txid: &Txid,
+    merkle_root: &TxMerkleNode,
+    merkle_res: &GetMerkleRes,
+) -> bool {
+    let mut index = merkle_res.pos;
+    let mut cur = txid.to_raw_hash();
+    for mut bytes in merkle_res.merkle.iter().cloned() {
+        bytes.reverse();
+        let next_hash = Sha256d::from_byte_array(bytes);
+
+        cur = Sha256d::from_engine({
+            let mut engine = Sha256d::engine();
+            if index % 2 == 0 {
+                engine.input(cur.as_ref());
+                engine.input(next_hash.as_ref());
+            } else {
+                engine.input(next_hash.as_ref());
+                engine.input(cur.as_ref());
+            };
+            engine
+        });
+        index /= 2;
+    }
+
+    cur == merkle_root.to_raw_hash()
+}