Expand description
Unilateral exit management
This module coordinates unilateral exits of VTXOs back to on-chain bitcoin without requiring any third-party cooperation. It tracks which VTXOs should be exited, prepares and signs the required transactions, and drives the process forward until the funds are confirmed and claimable.
What this module provides
- Discovery, tracking, and persistence of the exit state for VTXOs.
- Initiation of exits for the entire wallet or a selected set of VTXOs.
- Periodic progress of exits (broadcasting, fee-bumping, and state updates).
- APIs to inspect the current exit status, history, and related transactions.
- Construction and signing of a final claim (drain) transaction once exits become claimable.
When to use this module
- Whenever VTXOs must be unilaterally moved on-chain, e.g., during counterparty unavailability, or when the counterparty turns malicious.
When not to use this module
- If the server is cooperative. You can always offboard or pay onchain in a way that is much cheaper and faster.
Core types
- Exit: High-level coordinator for the exit workflow. It persists state and advances unilateral exits until they are claimable.
- ExitVtxo: A VTXO marked for, and progressing through, unilateral exit. Each instance exposes its current state and related metadata.
Typical lifecycle
- Choose what to exit
- Mark individual VTXOs for exit with Exit::start_exit_for_vtxos, or exit everything with Exit::start_exit_for_entire_wallet.
- Drive progress
- Periodically call Exit::progress_exits to advance the exit process. This will create or update transactions, adjust fees for existing transactions, and refresh the status of each unilateral exit until it has been confirmed and subsequentially spent onchain.
- Exit::sync_exit can be used to re-sync state with the blockchain and mempool without taking progress actions.
- Inspect status
- Use Exit::get_exit_status for detailed per-VTXO status (optionally including history and transactions).
- Use Exit::get_exit_vtxos or Exit::list_claimable to browse tracked exits and locate those that are fully confirmed onchain.
- Claim the exited funds (optional)
- Once your transaction is confirmed onchain the funds are fully yours. However, recovery from seed is not supported. By claiming your VTXO you move them to your onchain wallet.
- Once claimable, construct a PSBT to drain them with Exit::drain_exits.
- Alternatively, you can use Exit::sign_exit_claim_inputs to sign the inputs of a given PSBT if any are the outputs of a claimable unilateral exit.
Fees rates
- Suitable fee rates will be calculated based on the current network conditions, however, if you wish to override this, you can do so by providing your own FeeRate in Exit::progress_exits and Exit::drain_exits
Error handling and persistence
- The coordinator surfaces operational errors via anyhow::Result and domain-specific errors via ExitError where appropriate. Persistent state is kept via the configured persister and refreshed against the current chain view provided by the chain source client.
Minimal example (high-level):
let (mut bark_wallet, mut onchain_wallet) = get_wallets().await;
// Mark all VTXOs for exit.
bark_wallet.exit.get_mut().start_exit_for_entire_wallet(&onchain_wallet).await?;
// Transactions will be broadcast and require confirmations so keep periodically calling this.
bark_wallet.exit.get_mut().progress_exits(&mut onchain_wallet, None).await?;
// Once all VTXOs are claimable, construct a PSBT to drain them.
let drain_to = bitcoin::Address::from_str("bc1p...")?.assume_checked();
let exit = bark_wallet.exit.read().await;
let drain_psbt = exit.drain_exits(
&exit.list_claimable(),
&bark_wallet,
drain_to,
None,
).await?;
// Next you should broadcast the PSBT, once it's confirmed the unilateral exit is complete.
// broadcast_psbt(drain_psbt).await?;