bark/persist/

mod.rs

//! Persistence abstractions for Bark wallets.
//!
//! This module defines the [BarkPersister] trait and related data models used by the
//! wallet to store and retrieve state. Implementors can provide their own storage backends
//! (e.g., SQLite, PostgreSQL, in-memory, mobile key/value stores) by implementing the
//! [BarkPersister] trait.
//!
//! Design goals
//! - Clear separation between wallet logic and storage.
//! - Transactional semantics where appropriate (round state transitions, movement recording).
//! - Portability across different platforms and environments.
//!
//! Typical usage
//! - Applications construct a concrete persister (for example, a SQLite-backed client) and
//!   pass it to the [crate::Wallet]. The [crate::Wallet] only depends on this trait for reads/writes.
//! - Custom wallet implementations can reuse this trait to remain compatible with Bark
//!   storage expectations without depending on a specific database.
//! - A default rusqlite implementation is provided by [sqlite::SqliteClient].

pub mod adaptor;
pub mod models;
#[cfg(feature = "sqlite")]
pub mod sqlite;
#[cfg(test)]
pub(crate) mod test_suite;


use bitcoin::{Amount, Transaction, Txid};
use bitcoin::secp256k1::PublicKey;
use chrono::DateTime;
use lightning_invoice::Bolt11Invoice;
#[cfg(feature = "onchain-bdk")]
use bdk_wallet::ChangeSet;

use ark::{Vtxo, VtxoId};
use ark::lightning::{Invoice, PaymentHash, Preimage};
use ark::vtxo::Full;
use bitcoin_ext::BlockDelta;

use crate::WalletProperties;
use crate::exit::ExitTxOrigin;
use crate::persist::models::{
	LightningReceive, LightningSend, PendingBoard, RoundStateId, StoredExit, StoredRoundState,
	Unlocked, PendingOffboard,
};
use crate::movement::{Movement, MovementId, MovementStatus, MovementSubsystem, PaymentMethod};
use crate::round::RoundState;
use crate::vtxo::{VtxoState, VtxoStateKind, WalletVtxo};

/// Storage interface for Bark wallets.
///
/// Implement this trait to plug a custom persistence backend. The wallet uses it to:
/// - Initialize and read wallet properties and configuration.
/// - Record movements (spends/receives), recipients, and enforce [Vtxo] state transitions.
/// - Manage round lifecycles (attempts, pending confirmation, confirmations/cancellations).
/// - Persist ephemeral protocol artifacts (e.g., secret nonces) transactionally.
/// - Track Lightning receives and preimage revelation.
/// - Track exit-related data and associated child transactions.
/// - Persist the last synchronized Ark block height.
///
/// Feature integration:
/// - With the `onchain-bdk` feature, methods are provided to initialize and persist a BDK
///   wallet ChangeSet in the same storage.
///
/// Notes for implementors:
/// - Ensure that operations that change multiple records (e.g., registering a movement,
///   storing round state transitions) are executed transactionally.
/// - Enforce state integrity by verifying allowed_old_states before updating a [Vtxo] state.
/// - If your backend is not thread-safe, prefer a short-lived connection per call or use
///   an internal pool with checked-out connections per operation.
/// - Return precise errors so callers can surface actionable diagnostics.
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
pub trait BarkPersister: Send + Sync + 'static {
	/// Check if the wallet is initialized.
	///
	/// Returns:
	/// - `Ok(true)` if the wallet is initialized.
	/// - `Ok(false)` if the wallet is not initialized.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn is_initialized(&self) -> anyhow::Result<bool> {
		Ok(self.read_properties().await?.is_some())
	}

	/// Initialize a wallet in storage with the provided properties.
	///
	/// Call exactly once per wallet database. Subsequent calls should fail to prevent
	/// accidental re-initialization.
	///
	/// Parameters:
	/// - properties: WalletProperties to persist (e.g., network, descriptors, metadata).
	///
	/// Returns:
	/// - `Ok(())` on success.
	///
	/// Errors:
	/// - Returns an error if the wallet is already initialized or if persistence fails.
	async fn init_wallet(&self, properties: &WalletProperties) -> anyhow::Result<()>;

	/// Initialize the onchain BDK wallet and return any previously stored ChangeSet.
	///
	/// Must be called before storing any new BDK changesets to bootstrap the BDK state.
	///
	/// Feature: only available with `onchain-bdk`.
	///
	/// Returns:
	/// - `Ok(ChangeSet)` containing the previously persisted BDK state (possibly empty).
	///
	/// Errors:
	/// - Returns an error if the BDK state cannot be created or loaded.
	#[cfg(feature = "onchain-bdk")]
	async fn initialize_bdk_wallet(&self) -> anyhow::Result<ChangeSet>;

	/// Persist an incremental BDK ChangeSet.
	///
	/// The changeset should be applied atomically. Callers typically obtain the changeset
	/// from a BDK wallet instance after mutating wallet state (e.g., sync).
	///
	/// Feature: only available with `onchain-bdk`.
	///
	/// Parameters:
	/// - changeset: The BDK ChangeSet to persist.
	///
	/// Errors:
	/// - Returns an error if the changeset cannot be written.
	#[cfg(feature = "onchain-bdk")]
	async fn store_bdk_wallet_changeset(&self, changeset: &ChangeSet) -> anyhow::Result<()>;

	/// Read wallet properties from storage.
	///
	/// Returns:
	/// - `Ok(Some(WalletProperties))` if the wallet has been initialized.
	/// - `Ok(None)` if no wallet exists yet.
	///
	/// Errors:
	/// - Returns an error on I/O or deserialization failures.
	async fn read_properties(&self) -> anyhow::Result<Option<WalletProperties>>;

	/// Set the server public key in wallet properties.
	///
	/// This is used to store the server pubkey for existing wallets that were
	/// created before server pubkey tracking was added. Once set, the wallet
	/// will verify the server pubkey on every connection.
	///
	/// Parameters:
	/// - server_pubkey: The server's public key to store.
	///
	/// Errors:
	/// - Returns an error if the update fails.
	async fn set_server_pubkey(&self, server_pubkey: PublicKey) -> anyhow::Result<()>;

	/// Creates a new movement in the given state, ready to be updated.
	///
	/// Parameters:
	/// - status: The desired status for the new movement.
	/// - subsystem: The subsystem that created the movement.
	/// - time: The time the movement should be marked as created.
	///
	/// Returns:
	/// - `Ok(MovementId)` of the newly created movement.
	///
	/// Errors:
	/// - Returns an error if the movement is unable to be created.
	async fn create_new_movement(&self,
		status: MovementStatus,
		subsystem: &MovementSubsystem,
		time: DateTime<chrono::Local>,
	) -> anyhow::Result<MovementId>;

	/// Persists the given movement state.
	///
	/// Parameters:
	/// - movement: The movement and its associated data to be persisted.
	///
	/// Errors:
	/// - Returns an error if updating the movement fails for any reason.
	async fn update_movement(&self, movement: &Movement) -> anyhow::Result<()>;

	/// Gets the movement with the given [MovementId].
	///
	/// Parameters:
	/// - movement_id: The ID of the movement to retrieve.
	///
	/// Returns:
	/// - `Ok(Movement)` if the movement exists.
	///
	/// Errors:
	/// - If the movement does not exist.
	/// - If retrieving the movement fails.
	async fn get_movement_by_id(&self, movement_id: MovementId) -> anyhow::Result<Movement>;

	/// Gets every stored movement.
	///
	/// Returns:
	/// - `Ok(Vec<Movement>)` containing all movements, empty if none exist.
	///
	/// Errors:
	/// - If retrieving the movements fails.
	async fn get_all_movements(&self) -> anyhow::Result<Vec<Movement>>;

	/// Get all movements for a given payment method
	///
	/// Parameters:
	/// - `payment_method`: The [PaymentMethod] to look up.
	///
	/// Returns:
	/// - `Ok(movements)` containing all relevant movements, empty if none exist.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_movements_by_payment_method(
		&self,
		payment_method: &PaymentMethod,
	) -> anyhow::Result<Vec<Movement>>;

	/// Store a pending board.
	///
	/// Parameters:
	/// - vtxo: The [Vtxo] to store.
	/// - funding_txid: The funding [Txid].
	/// - movement_id: The [MovementId] associated with this board.
	///
	/// Errors:
	/// - Returns an error if the board cannot be stored.
	async fn store_pending_board(
		&self,
		vtxo: &Vtxo<Full>,
		funding_tx: &Transaction,
		movement_id: MovementId,
	) -> anyhow::Result<()>;

	/// Remove a pending board.
	///
	/// Parameters:
	/// - vtxo_id: The [VtxoId] to remove.
	///
	/// Errors:
	/// - Returns an error if the board cannot be removed.
	async fn remove_pending_board(&self, vtxo_id: &VtxoId) -> anyhow::Result<()>;

	/// Get the [VtxoId] for each pending board.
	///
	/// Returns:
	/// - `Ok(Vec<VtxoId>)` possibly empty.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_all_pending_board_ids(&self) -> anyhow::Result<Vec<VtxoId>>;

	/// Get the [PendingBoard] associated with the given [VtxoId].
	///
	/// Returns:
	/// - `Ok(Some(PendingBoard))` if a matching board exists
	/// - `Ok(None)` if no matching board exists
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_pending_board_by_vtxo_id(&self, vtxo_id: VtxoId) -> anyhow::Result<Option<PendingBoard>>;

	/// Store a new ongoing round state and lock the VTXOs in round
	///
	/// Parameters:
	/// - `round_state`: the state to store
	///
	/// Returns:
	/// - `RoundStateId`: the storaged ID of the new state
	///
	/// Errors:
	/// - returns an error of the new round state could not be stored or the VTXOs
	///   couldn't be marked as locked
	async fn store_round_state_lock_vtxos(&self, round_state: &RoundState) -> anyhow::Result<RoundStateId>;

	/// Update an existing stored pending round state
	///
	/// Parameters:
	/// - `round_state`: the round state to update
	///
	/// Errors:
	/// - returns an error of the existing round state could not be found or updated
	async fn update_round_state(&self, round_state: &StoredRoundState) -> anyhow::Result<()>;

	/// Remove a pending round state from the db
	///
	/// Parameters:
	/// - `round_state`: the round state to remove
	///
	/// Errors:
	/// - returns an error of the existing round state could not be found or removed
	async fn remove_round_state(&self, round_state: &StoredRoundState) -> anyhow::Result<()>;

	/// Load a single round state by its id
	///
	/// Returns:
	/// - `Option<StoredRoundState>`: the stored round state if found, `None` otherwise
	///
	/// Errors:
	/// - returns an error of the states could not be succesfully retrieved
	async fn get_round_state_by_id(&self, id: RoundStateId) -> anyhow::Result<Option<StoredRoundState<Unlocked>>>;

	/// Load all pending round states from the db
	///
	/// Returns:
	/// - `Vec<RoundStateId>`: unordered vector with all stored round state ids
	///
	/// Errors:
	/// - returns an error of the ids could not be succesfully retrieved
	async fn get_pending_round_state_ids(&self) -> anyhow::Result<Vec<RoundStateId>>;

	/// Stores VTXOs with their initial state.
	///
	/// This operation is idempotent: if a VTXO already exists (same `id`), the
	/// implementation should succeed without modifying the existing VTXO or its
	/// state. This allows safe retries during crash recovery scenarios.
	///
	/// # Parameters
	/// - `vtxos`: Slice of VTXO and state pairs to store.
	///
	/// # Behavior
	/// - For each VTXO that does not exist: inserts the VTXO and its initial state.
	/// - For each VTXO that already exists: no-op for that VTXO.
	///
	/// # Errors
	/// - Returns an error if the storage operation fails.
	async fn store_vtxos(
		&self,
		vtxos: &[(&Vtxo<Full>, &VtxoState)],
	) -> anyhow::Result<()>;

	/// Fetch a wallet [Vtxo] with its current state by ID.
	///
	/// Parameters:
	/// - id: [VtxoId] to look up.
	///
	/// Returns:
	/// - `Ok(Some(WalletVtxo))` if found,
	/// - `Ok(None)` otherwise.
	///
	/// Errors:
	/// - Returns an error if the lookup fails.
	async fn get_wallet_vtxo(&self, id: VtxoId) -> anyhow::Result<Option<WalletVtxo>>;

	/// Fetch all wallet VTXOs in the database.
	///
	/// Returns:
	/// - `Ok(Vec<WalletVtxo>)` possibly empty.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_all_vtxos(&self) -> anyhow::Result<Vec<WalletVtxo>>;

	/// Fetch all wallet VTXOs whose state matches any of the provided kinds.
	///
	/// Parameters:
	/// - state: Slice of `VtxoStateKind` filters.
	///
	/// Returns:
	/// - `Ok(Vec<WalletVtxo>)` possibly empty.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_vtxos_by_state(&self, state: &[VtxoStateKind]) -> anyhow::Result<Vec<WalletVtxo>>;

	/// Remove a [Vtxo] by ID.
	///
	/// Parameters:
	/// - id: `VtxoId` to remove.
	///
	/// Returns:
	/// - `Ok(Some(Vtxo))` with the removed [Vtxo] data if it existed,
	/// - `Ok(None)` otherwise.
	///
	/// Errors:
	/// - Returns an error if the delete operation fails.
	async fn remove_vtxo(&self, id: VtxoId) -> anyhow::Result<Option<Vtxo<Full>>>;

	/// Check whether a [Vtxo] is already marked spent.
	///
	/// Parameters:
	/// - id: VtxoId to check.
	///
	/// Returns:
	/// - `Ok(true)` if spent,
	/// - `Ok(false)` if not found or not spent.
	///
	/// Errors:
	/// - Returns an error if the lookup fails.
	async fn has_spent_vtxo(&self, id: VtxoId) -> anyhow::Result<bool>;

	/// Store a newly derived/assigned [Vtxo] public key index mapping.
	///
	/// Parameters:
	/// - index: Derivation index.
	/// - public_key: PublicKey at that index.
	///
	/// Errors:
	/// - Returns an error if the mapping cannot be stored.
	async fn store_vtxo_key(&self, index: u32, public_key: PublicKey) -> anyhow::Result<()>;

	/// Get the last revealed/used [Vtxo] key index.
	///
	/// Returns:
	/// - `Ok(Some(u32))` if a key was stored
	/// - `Ok(None)` otherwise.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_last_vtxo_key_index(&self) -> anyhow::Result<Option<u32>>;

	/// Retrieves the derivation index of the provided [PublicKey] from the database
	///
	/// Returns:
	/// - `Ok(Some(u32))` if the key was stored.
	/// - `Ok(None)` if the key was not stored.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_public_key_idx(&self, public_key: &PublicKey) -> anyhow::Result<Option<u32>>;

	/// Retrieves the mailbox checkpoint from the database
	///
	/// Returns:
	/// - `Ok(u64)` the stored checkpoint.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_mailbox_checkpoint(&self) -> anyhow::Result<u64>;

	/// Update the mailbox checkpoint to the new checkpoint
	///
	/// Returns:
	///
	///
	/// Errors:
	/// - Returns error when the query fails
	/// - Returns error when the provided checkpoint is smaller than the existing checkpoint
	async fn store_mailbox_checkpoint(&self, checkpoint: u64) -> anyhow::Result<()>;

	/// Store a new pending lightning send.
	///
	/// Parameters:
	/// - invoice: The invoice of the pending lightning send.
	/// - amount: The amount of the pending lightning send.
	/// - fee: The fee of the pending lightning send.
	/// - vtxos: The vtxos of the pending lightning send.
	/// - movement_id: The movement ID associated with this send.
	///
	/// Errors:
	/// - Returns an error if the pending lightning send cannot be stored.
	async fn store_new_pending_lightning_send(
		&self,
		invoice: &Invoice,
		amount: Amount,
		fee: Amount,
		vtxos: &[VtxoId],
		movement_id: MovementId,
	) -> anyhow::Result<LightningSend>;

	/// Get all pending lightning sends.
	///
	/// Returns:
	/// - `Ok(Vec<LightningSend>)` possibly empty.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_all_pending_lightning_send(&self) -> anyhow::Result<Vec<LightningSend>>;

	/// Mark a lightning send as finished.
	///
	/// Parameters:
	/// - payment_hash: The [PaymentHash] of the lightning send to update.
	/// - preimage: The [Preimage] of the successful lightning send.
	///
	/// Errors:
	/// - Returns an error if the lightning send cannot be updated.
	async fn finish_lightning_send(
		&self,
		payment_hash: PaymentHash,
		preimage: Option<Preimage>,
	) -> anyhow::Result<()>;

	/// Remove a lightning send.
	///
	/// Parameters:
	/// - payment_hash: The [PaymentHash] of the lightning send to remove.
	///
	/// Errors:
	/// - Returns an error if the lightning send cannot be removed.
	async fn remove_lightning_send(&self, payment_hash: PaymentHash) -> anyhow::Result<()>;

	/// Get a lightning send by payment hash
	///
	/// Parameters:
	/// - payment_hash: The [PaymentHash] of the lightning send to get.
	///
	/// Errors:
	/// - Returns an error if the lookup fails.
	async fn get_lightning_send(&self, payment_hash: PaymentHash) -> anyhow::Result<Option<LightningSend>>;

	/// Store an incoming Lightning receive record.
	///
	/// Parameters:
	/// - payment_hash: Unique payment hash.
	/// - preimage: Payment preimage (kept until disclosure).
	/// - invoice: The associated BOLT11 invoice.
	/// - htlc_recv_cltv_delta: The CLTV delta for the HTLC VTXO.
	///
	/// Errors:
	/// - Returns an error if the receive cannot be stored.
	async fn store_lightning_receive(
		&self,
		payment_hash: PaymentHash,
		preimage: Preimage,
		invoice: &Bolt11Invoice,
		htlc_recv_cltv_delta: BlockDelta,
	) -> anyhow::Result<()>;

	/// Returns a list of all pending lightning receives
	///
	/// Returns:
	/// - `Ok(Vec<LightningReceive>)` possibly empty.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_all_pending_lightning_receives(&self) -> anyhow::Result<Vec<LightningReceive>>;

	/// Mark a Lightning receive preimage as revealed (e.g., after settlement).
	///
	/// Parameters:
	/// - payment_hash: The payment hash identifying the receive.
	///
	/// Errors:
	/// - Returns an error if the update fails or the receive does not exist.
	async fn set_preimage_revealed(&self, payment_hash: PaymentHash) -> anyhow::Result<()>;

	/// Set the VTXO IDs and [MovementId] for a [LightningReceive].
	///
	/// Parameters:
	/// - payment_hash: The payment hash identifying the receive.
	/// - htlc_vtxo_ids: The VTXO IDs to set.
	/// - movement_id: The movement ID associated with the invoice.
	///
	/// Errors:
	/// - Returns an error if the update fails or the receive does not exist.
	async fn update_lightning_receive(
		&self,
		payment_hash: PaymentHash,
		htlc_vtxo_ids: &[VtxoId],
		movement_id: MovementId,
	) -> anyhow::Result<()>;

	/// Fetch a Lightning receive by its payment hash.
	///
	/// Parameters:
	/// - payment_hash: The payment hash to look up.
	///
	/// Returns:
	/// - `Ok(Some(LightningReceive))` if found,
	/// - `Ok(None)` otherwise.
	///
	/// Errors:
	/// - Returns an error if the lookup fails.
	async fn fetch_lightning_receive_by_payment_hash(
		&self,
		payment_hash: PaymentHash,
	) -> anyhow::Result<Option<LightningReceive>>;

	/// Mark a Lightning receive as finished by its payment hash.
	///
	/// Parameters:
	/// - payment_hash: The payment hash of the record to mark finished
	///
	/// Errors:
	/// - Returns an error if the operation fails.
	async fn finish_pending_lightning_receive(
		&self,
		payment_hash: PaymentHash,
	) -> anyhow::Result<()>;

	/// Store an entry indicating a [Vtxo] is being exited.
	///
	/// Parameters:
	/// - exit: StoredExit describing the exit operation.
	///
	/// Errors:
	/// - Returns an error if the entry cannot be stored.
	async fn store_exit_vtxo_entry(&self, exit: &StoredExit) -> anyhow::Result<()>;

	/// Remove an exit entry for a given [Vtxo] ID.
	///
	/// Parameters:
	/// - id: VtxoId to remove from exit tracking.
	///
	/// Errors:
	/// - Returns an error if the removal fails.
	async fn remove_exit_vtxo_entry(&self, id: &VtxoId) -> anyhow::Result<()>;

	/// List all VTXOs currently tracked as being exited.
	///
	/// Returns:
	/// - `Ok(Vec<StoredExit>)` possibly empty.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_exit_vtxo_entries(&self) -> anyhow::Result<Vec<StoredExit>>;

	/// Store a child transaction related to an exit transaction.
	///
	/// Parameters:
	/// - exit_txid: The parent exit transaction ID.
	/// - child_tx: The child bitcoin Transaction to store.
	/// - origin: Metadata describing where the child came from (ExitTxOrigin).
	///
	/// Errors:
	/// - Returns an error if the transaction cannot be stored.
	async fn store_exit_child_tx(
		&self,
		exit_txid: Txid,
		child_tx: &Transaction,
		origin: ExitTxOrigin,
	) -> anyhow::Result<()>;

	/// Retrieve a stored child transaction for a given exit transaction ID.
	///
	/// Parameters:
	/// - exit_txid: The parent exit transaction ID.
	///
	/// Returns:
	/// - `Ok(Some((Transaction, ExitTxOrigin)))` if found,
	/// - `Ok(None)` otherwise.
	///
	/// Errors:
	/// - Returns an error if the lookup fails.
	async fn get_exit_child_tx(
		&self,
		exit_txid: Txid,
	) -> anyhow::Result<Option<(Transaction, ExitTxOrigin)>>;

	/// Updates the state of the VTXO corresponding to the given [VtxoId], provided that their
	/// current state is one of the given `allowed_states`.
	///
	/// # Parameters
	/// - `vtxo_id`: The ID of the [Vtxo] to update.
	/// - `state`: The new state to be set for the specified [Vtxo].
	/// - `allowed_states`: An iterable collection of allowed states ([VtxoStateKind]) that the
	///   [Vtxo] must currently be in for their state to be updated to the new `state`.
	///
	/// # Returns
	/// - `Ok(WalletVtxo)` if the state update is successful.
	/// - `Err(anyhow::Error)` if the VTXO fails to meet the required conditions,
	///    or if another error occurs during the operation.
	///
	/// # Errors
	/// - Returns an error if the current state is not within the `allowed_states`.
	/// - Returns an error for any other issues encountered during the operation.
	async fn update_vtxo_state_checked(
		&self,
		vtxo_id: VtxoId,
		new_state: VtxoState,
		allowed_old_states: &[VtxoStateKind],
	) -> anyhow::Result<WalletVtxo>;

	/// Store a pending offboard record.
	///
	/// Parameters:
	/// - pending: The [PendingOffboard] to store.
	///
	/// Errors:
	/// - Returns an error if the record cannot be stored.
	async fn store_pending_offboard(
		&self,
		pending: &PendingOffboard,
	) -> anyhow::Result<()>;

	/// Get all pending offboard records.
	///
	/// Returns:
	/// - `Ok(Vec<PendingOffboard>)` possibly empty.
	///
	/// Errors:
	/// - Returns an error if the query fails.
	async fn get_pending_offboards(&self) -> anyhow::Result<Vec<PendingOffboard>>;

	/// Remove a pending offboard record by its [MovementId].
	///
	/// Parameters:
	/// - movement_id: The [MovementId] to remove.
	///
	/// Errors:
	/// - Returns an error if the record cannot be removed.
	async fn remove_pending_offboard(&self, movement_id: MovementId) -> anyhow::Result<()>;
}