Blockchain Clients

LWK supports different ways to retrieve wallet data from the Liquid blockchain:

• Electrum - TCP-based protocol, widely supported
• Esplora - HTTP-based REST API, browser-compatible
• Waterfalls - Optimized HTTP-based protocol with reduced roundtrips

Some clients also come in different flavors: blocking or async. It's also possible to connect to authenticated backends for enterprise deployments.

Quick Comparison

Electrum

The Electrum protocol is the most widely used light-client syncing mechanism for Bitcoin and Liquid wallets.

Key characteristics:

• Protocol: TCP-based
• Performance: Good
• Availability: Only blocking variant
• Platform support: Desktop, mobile, and server applications
• Browser support: ❌ No (TCP not available in browsers)
• Default servers: Blockstream public Electrum servers

This client is recommended for desktop, mobile, and server applications where interoperability is critical. By default, Blockstream public Electrum servers are used, but you can also specify custom URLs for private or local deployments.

use lwk_wollet::{ElectrumClient, ElectrumUrl};

let electrum_url = ElectrumUrl::new("blockstream.info:995", true, true)?;
let client = ElectrumClient::new(&electrum_url)?;

# Create electrum client with custom URL
client = ElectrumClient("blockstream.info:995", tls=True, validate_domain=True)

# Or use the default electrum client for the network
default_client = Network.mainnet().default_electrum_client()

Esplora

The Esplora client is based on the Esplora API, a popular HTTP-based blockchain explorer API.

Key characteristics:

• Protocol: HTTP/HTTPS REST API
• Performance: Multiple roundtrips required for wallet sync
• Availability: Both blocking and async variants
• Browser support: ✅ Yes, works in web browsers
• Authentication: Supports OAuth2 for enterprise deployments

This client is ideal for web applications and scenarios where HTTP-based communication is required. While it requires more roundtrips than Electrum, it's the only option for browser-based applications and offers broad compatibility.

use lwk_wollet::clients::blocking::EsploraClient;

let esplora_url = "https://blockstream.info/liquid/api";
let client = EsploraClient::new(esplora_url, ElementsNetwork::Liquid)?;

url = "https://blockstream.info/liquid/api"
client = EsploraClient(url, Network.mainnet())

const url_esplora = "https://blockstream.info/liquid/api";
const esplora_client = new lwk.EsploraClient(lwk.Network.liquid(), url_esplora, true, 4, false);

Authenticated Esplora

Some Esplora servers, particularly enterprise deployments like Blockstream Enterprise, require authentication for access. LWK supports OAuth2-based authentication with automatic token refresh.

Use authenticated clients when:

• Connecting to private or enterprise Esplora instances
• Requiring guaranteed rate limits and service quality
• Needing additional privacy and dedicated infrastructure

use lwk_wollet::clients::asyncr::{EsploraClient as AsyncEsploraClient, EsploraClientBuilder};
use lwk_wollet::clients::TokenProvider;

let base_url = "https://enterprise.blockstream.info/liquid/api";
let client_id = "your_client_id";
let client_secret = "your_client_secret";
let login_url =
    "https://login.blockstream.com/realms/blockstream-public/protocol/openid-connect/token";

let mut client = EsploraClientBuilder::new(base_url, ElementsNetwork::Liquid)
    .token_provider(TokenProvider::Blockstream {
        url: login_url.to_string(),
        client_id: client_id.to_string(),
        client_secret: client_secret.to_string(),
    })
    .build()?;

Waterfalls

Waterfalls is an optimized blockchain indexer designed to significantly reduce the number of roundtrips required for wallet synchronization compared to traditional Esplora.

Key characteristics:

• Protocol: HTTP/HTTPS REST API (Esplora-compatible with extensions)
• Performance: Fewer roundtrips than standard Esplora, faster sync times
• Availability: Both blocking and async variants
• Browser support: ✅ Yes, works in web browsers
• Maturity: Newer technology, still evolving

Important: The public Waterfalls instance shown in the examples (waterfalls.liquidwebwallet.org) is provided for testing and development only.

let waterfalls_url = "https://waterfalls.liquidwebwallet.org/liquid/api";
let client = EsploraClient::new_waterfalls(waterfalls_url, ElementsNetwork::Liquid).unwrap();

url = "https://waterfalls.liquidwebwallet.org/liquid/api"
client = EsploraClient.new_waterfalls(url, Network.mainnet())

const url_waterfalls = "https://waterfalls.liquidwebwallet.org/liquid/api";
const waterfalls_client = new lwk.EsploraClient(lwk.Network.liquid(), url_waterfalls, true, 4, false);

Authenticated Waterfalls

Authentication support for Waterfalls clients is planned for a future release. This will enable private Waterfalls instances with OAuth2 authentication, similar to authenticated Esplora clients.