Enrich rustdoc across public API surface

README.md

@@ -138,20 +138,49 @@ The wallet's behavior is controlled by `Tunables`:
 ## Supported Backends
 
 ### Trusted Wallet Backends
-- **Spark** - Custodial Lightning wallet (default)
-- **Cashu** - Ecash-based wallet
+
+#### Spark (default)
+
+Spark uses the [Breez Spark SDK](https://breez.technology) for custodial Lightning payments with instant settlement and low fees. This is the default backend and is enabled via the `spark` feature flag.
+
+```rust,no_run
+use orange_sdk::trusted_wallet::spark::SparkWalletConfig;
+use orange_sdk::ExtraConfig;
+
+let extra = ExtraConfig::Spark(SparkWalletConfig::default());
+```
+
+#### Cashu
+
+Cashu uses the [Cashu Development Kit (CDK)](https://docs.rs/cdk) for ecash-based custody via a Cashu mint. Enable it with the `cashu` feature flag:
+
+```toml
+[dependencies]
+orange-sdk = { version = "0.1", features = ["cashu"] }
+```
+
+```rust,ignore
+use orange_sdk::trusted_wallet::cashu::CashuConfig;
+use orange_sdk::{CurrencyUnit, ExtraConfig};
+
+let extra = ExtraConfig::Cashu(CashuConfig {
+    mint_url: "https://mint.example.com".to_string(),
+    unit: CurrencyUnit::Sat,
+    npubcash_url: Some("https://npub.cash".to_string()), // optional: enables Lightning address
+});
+```
 
 ### Chain Sources
-- Electrum servers
-- Esplora servers (with optional Basic auth)
-- Bitcoin Core RPC
+- **Electrum** servers (use `ssl://` prefix for TLS)
+- **Esplora** HTTP API servers (with optional Basic auth)
+- **Bitcoin Core RPC** (direct JSON-RPC connection)
 
 ## Documentation
 
 For detailed API documentation, run:
 
 ```bash
-cargo doc --open
+cargo doc --all-features --open
 ```
 
 ## Contributing

graduated-rebalancer/src/lib.rs

@@ -1,11 +1,34 @@
 #![deny(missing_docs)]
 #![allow(clippy::type_complexity)]
 
-//! A library for managing graduated rebalancing between trusted and lightning wallets.
+//! Graduated rebalancing between trusted and Lightning wallets.
 //!
-//! This crate provides a `GraduatedRebalancer` that automatically manages the balance
-//! between trusted wallets (for small amounts) and lightning wallets (for larger amounts)
-//! based on configurable thresholds.
+//! This crate provides [`GraduatedRebalancer`], a generic engine that automatically moves
+//! funds from a trusted wallet backend into self-custodial Lightning channels based on
+//! configurable thresholds.
+//!
+//! # How it works
+//!
+//! The rebalancer supports two transfer paths:
+//!
+//! 1. **Trusted → Lightning:** When the trusted wallet balance exceeds the configured limit,
+//!    the rebalancer pays a Lightning invoice from the trusted wallet to the self-custodial
+//!    Lightning node, effectively moving funds into self-custody.
+//!
+//! 2. **On-chain → Lightning:** When on-chain funds are available, the rebalancer opens a
+//!    new Lightning channel or splices funds into an existing channel with the LSP.
+//!
+//! Both paths are triggered via the [`RebalanceTrigger`] trait, which determines *when* and
+//! *how much* to rebalance. Events are reported via the [`EventHandler`] trait.
+//!
+//! # Usage
+//!
+//! This crate is designed to be generic over wallet implementations. Provide types that
+//! implement [`TrustedWallet`] and [`LightningWallet`], along with a [`RebalanceTrigger`]
+//! and an [`EventHandler`], then construct a [`GraduatedRebalancer`].
+//!
+//! The [`orange-sdk`](https://docs.rs/orange-sdk) crate provides a concrete integration
+//! of this rebalancer with its wallet infrastructure.
 
 use bitcoin_payment_instructions::amount::Amount;
 use bitcoin_payment_instructions::PaymentMethod;
@@ -206,7 +229,16 @@ impl EventHandler for IgnoringEventHandler {
 	}
 }
 
-/// The main graduated rebalancer that manages balance between trusted and lightning wallets
+/// The core rebalancing engine.
+///
+/// Manages the automatic transfer of funds from a trusted wallet into self-custodial
+/// Lightning channels. It is generic over the wallet implementations, trigger logic,
+/// event handling, and logger.
+///
+/// All rebalance operations are serialized through an internal mutex to prevent
+/// concurrent balance modifications.
+///
+/// See the [crate-level documentation](crate) for an overview of how rebalancing works.
 pub struct GraduatedRebalancer<
 	T: TrustedWallet,
 	L: LightningWallet,

orange-sdk/src/event.rs

@@ -23,7 +23,29 @@ pub(crate) const EVENT_QUEUE_PERSISTENCE_PRIMARY_NAMESPACE: &str = "";
 pub(crate) const EVENT_QUEUE_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
 pub(crate) const EVENT_QUEUE_PERSISTENCE_KEY: &str = "orange_events";
 
-/// An event emitted by [`Wallet`], which should be handled by the user.
+/// An event emitted by [`Wallet`] that should be handled by the user.
+///
+/// Events are retrieved via [`Wallet::next_event`](crate::Wallet::next_event),
+/// [`Wallet::next_event_async`](crate::Wallet::next_event_async), or
+/// [`Wallet::wait_next_event`](crate::Wallet::wait_next_event). After processing an event,
+/// you **must** call [`Wallet::event_handled`](crate::Wallet::event_handled) to advance the queue.
+///
+/// Events are persisted, so they will survive process restarts and will be re-delivered
+/// until acknowledged.
+///
+/// # Event types
+///
+/// | Event | Meaning |
+/// |-------|---------|
+/// | [`PaymentSuccessful`](Self::PaymentSuccessful) | An outgoing payment completed |
+/// | [`PaymentFailed`](Self::PaymentFailed) | An outgoing payment failed |
+/// | [`PaymentReceived`](Self::PaymentReceived) | An incoming Lightning payment arrived |
+/// | [`OnchainPaymentReceived`](Self::OnchainPaymentReceived) | An incoming on-chain payment arrived |
+/// | [`ChannelOpened`](Self::ChannelOpened) | A Lightning channel is ready to use |
+/// | [`ChannelClosed`](Self::ChannelClosed) | A Lightning channel was closed (rebalancing auto-disabled) |
+/// | [`RebalanceInitiated`](Self::RebalanceInitiated) | A trusted-to-Lightning rebalance started |
+/// | [`RebalanceSuccessful`](Self::RebalanceSuccessful) | A trusted-to-Lightning rebalance completed |
+/// | [`SplicePending`](Self::SplicePending) | An on-chain splice into a channel is pending confirmation |
 ///
 /// [`Wallet`]: [`crate::Wallet`]
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -201,9 +223,16 @@ impl_writeable_tlv_based_enum!(Event,
 	},
 );
 
-/// A queue for events emitted by the [`Wallet`].
+/// A persistent, ordered queue of [`Event`]s emitted by the [`Wallet`].
+///
+/// The queue is backed by the wallet's [`KVStore`] so events survive restarts. Events are
+/// delivered in FIFO order and remain at the head of the queue until acknowledged via
+/// [`Wallet::event_handled`](crate::Wallet::event_handled).
+///
+/// Users typically interact with this through the [`Wallet`] methods rather than directly.
 ///
 /// [`Wallet`]: [`crate::Wallet`]
+/// [`KVStore`]: ldk_node::lightning::util::persist::KVStore
 pub struct EventQueue {
 	queue: Arc<Mutex<VecDeque<Event>>>,
 	waker: Arc<Mutex<Option<Waker>>>,