doc: sendall

Author: valerio-vaccaro

docs/src/SUMMARY.md

@@ -19,7 +19,7 @@
   * [Burn](burn.md) ✅
   * [Manual Coin Selection]() #(manual.md) ❌
   * [Add External Inputs]() #(external.md) ❌
-  * [Send All Funds]() #(sendall.md) ❌
+  * [Send All Funds](sendall.md) ✅
   * [Explicit Input and Outputs]() #(explicit.md) ❌
   * [AMP0](amp0.md) ✅
   * [AMP2]() #(amp2.md) ❌

docs/src/sendall.md

@@ -1 +1,45 @@
 # Send All Funds
+Sending all funds (also called "draining" the wallet) allows you to send all LBTC (policy asset) from your wallet to a specified address in a single transaction. This is useful when you want to empty your wallet, consolidate UTXOs, or transfer all funds to another address.
+
+When you drain a wallet, all available LBTC UTXOs are selected as inputs, and after deducting transaction fees, the remaining amount is sent to the destination address. Note that draining only affects LBTC (the policy asset).
+
+"Drain" is only available for the asset used to pay fees (LBTC) with. For LBTC it's hard to guess the right amount to send all funds: it's the sum of all LBTC inputs minus the fee, but you don't know the actual fee until you created the transaction. So we need a way specify the TxBuilder to send all LBTC.
+
+For assets that are not LBTC, the caller can easily compute the sum of all asset in input and set the satoshi value explicitly.
+
+To send all LBTC, use `TxBuilder::drain_lbtc_wallet()`. By default LBTC are sent to a wallet address, if you want specify the destination address use `TxBuilder::drain_lbtc_to()`.
+
+The methods take the following arguments:
+
+1. **`drain_lbtc_wallet()`**: No arguments. Selects all available LBTC UTXOs from the wallet to be spent.
+2. **`drain_lbtc_to(address)`**: Takes an `Address` parameter specifying where to send all the LBTC after fees are deducted.
+
+<custom-tabs category="lang">
+<div slot="title">Rust</div>
+<section>
+
+```rust,ignore
+{{#include ../../lwk_wollet/tests/e2e.rs:drain_lbtc_wallet}}
+```
+
+</section>
+
+<div slot="title">Python</div>
+<section>
+
+```python
+{{#include ../../lwk_bindings/tests/bindings/external_utxos.py:drain_lbtc_wallet}}
+```
+
+</section>
+</custom-tabs>
+
+## Next Steps
+
+After sending all funds, you can:
+* Send other assets using regular [transaction creation](tx.md)
+* Receive new funds at any address in your wallet
+
+----
+
+Previous: [Burn](burn.md)

lwk_bindings/tests/bindings/external_utxos.py

@@ -32,13 +32,15 @@
     w2.is_segwit()
 )
 
+# ANCHOR: drain_lbtc_wallet
 node_addr = node.get_new_address()
-# Create speding tx sending all to the node
+# Create speding tx sending all to the node # ANCHOR: ignore
 builder = network.tx_builder()
-builder.add_external_utxos([utxo_w2])
+builder.add_external_utxos([utxo_w2]) # ANCHOR: ignore
 builder.drain_lbtc_wallet()
 builder.drain_lbtc_to(node_addr)
 pset = builder.finish(w1)
+# ANCHOR_END: drain_lbtc_wallet
 
 pset = s1.sign(pset)
 

lwk_wollet/tests/e2e.rs

@@ -2011,7 +2011,7 @@ fn wait_esplora_tx_update(client: &mut blocking::EsploraClient, wollet: &Wollet)
 
 #[cfg(feature = "esplora")]
 #[test]
-fn test_waterfalls_esplora() {
+fn test_waterfalls_esplora() -> Result<(), Box<dyn std::error::Error>> {
     // TODO: use TestWollet also for EsploraClient
     let env = TestEnvBuilder::from_env().with_waterfalls().build();
 
@@ -2039,13 +2039,14 @@ fn test_waterfalls_esplora() {
     let balance = wollet.balance().unwrap();
     assert_eq!(sats, *balance.get(&network.policy_asset()).unwrap());
 
+    // ANCHOR: drain_lbtc_wallet
     let address = env.elementsd_getnewaddress();
     let mut pset = wollet
         .tx_builder()
         .drain_lbtc_wallet()
         .drain_lbtc_to(address.clone())
-        .finish()
-        .unwrap();
+        .finish()?;
+    // ANCHOR_END: drain_lbtc_wallet
 
     let sigs = signer.sign(&mut pset).unwrap();
     assert!(sigs > 0);
@@ -2071,6 +2072,8 @@ fn test_waterfalls_esplora() {
     assert_eq!(history.len(), 1);
     assert_eq!(history[0].len(), 1);
     assert_eq!(history[0][0].txid, txid);
+
+    Ok(())
 }
 
 #[cfg(feature = "esplora")]