waterfalls-client 0.2.0

Waterfalls API client library. Supports plaintext, TLS and Onion servers. Blocking or async
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# waterfalls-client

[Waterfalls](https://github.com/RCasatta/waterfalls) API client library. Supports plaintext, TLS and Onion servers. Blocking or async.

## Overview

This library provides both blocking and asynchronous HTTP clients for interacting with Waterfalls servers. It supports querying transaction histories, UTXO data, and blockchain information using Bitcoin descriptors or addresses.

## Features

- **Blocking and Async clients** - Choose the right client for your use case
- **Waterfalls API support** - Query with descriptors or addresses  
- **Compatible endpoints** - Transaction retrieval, block headers, broadcasting
- **Proxy support** - SOCKS proxy support for privacy
- **TLS/SSL support** - Secure connections with multiple TLS backends
- **Retry logic** - Automatic retries for temporary failures

## Usage

### Creating a Client

```rust
use waterfalls_client::Builder;

// Blocking client
let builder = Builder::new("https://waterfalls.example.com/api");
let blocking_client = builder.build_blocking();

// Async client  
let builder = Builder::new("https://waterfalls.example.com/api");
let async_client = builder.build_async()?;
```

### Querying with Descriptors

```rust
// Query with a Bitcoin descriptor
let descriptor = "wpkh(xpub.../*)";
let response = client.waterfalls(descriptor).await?;

// Query with specific parameters
let response = client.waterfalls_version(descriptor, 2, None, None, false).await?;
```

### Querying with Addresses

```rust
use bitcoin::Address;

let addresses = vec![address1, address2];
let response = client.waterfalls_addresses(&addresses).await?;
```

### Compatible Endpoints

```rust
// Get transaction
let tx = client.get_tx(&txid).await?;

// Get block header  
let header = client.get_header_by_hash(&block_hash).await?;

// Get tip hash
let tip = client.get_tip_hash().await?;

// Broadcast transaction
client.broadcast(&transaction).await?;
```

## Testing

The library includes comprehensive unit and integration tests.

### Unit Tests

Run the unit tests (no external dependencies required):

```bash
nix develop -c cargo test --lib
```

### Simple Integration Tests

Basic integration tests that don't require external dependencies:

```bash
nix develop -c cargo test --test simple_integration
```

These verify client construction, error handling, and API signatures.

### Full Integration Tests

**Note**: Uses waterfalls 0.9.4+ with type conversions between waterfalls::be and bitcoin types.

Integration tests require a running Waterfalls server with bitcoind. The tests use the `waterfalls` crate's `test_env` feature to automatically set up test environments.

**Prerequisites:**
- Environment variables `BITCOIND_EXEC` and `ELEMENTSD_EXEC` are automatically set in the nix environment

**Run integration tests:**
```bash
nix develop -c cargo test --test integration
```

The integration tests cover:
- All waterfalls-specific endpoints (`waterfalls`, `waterfalls_addresses`, etc.)
- Compatible Esplora endpoints (`get_tx`, `get_header_by_hash`, etc.)  
- Server information endpoints (`server_recipient`, `server_address`)
- Both blocking and async clients
- Type conversions from waterfalls::be types to bitcoin types

## Development

This project uses Nix for reproducible development environments:

```bash
nix develop  # Enter development shell
cargo check  # Check compilation
cargo test   # Run tests
```