Trait BarkPersister

pub trait BarkPersister:
    Send
    + Sync
    + 'static {
    // Required methods
    fn init_wallet(&self, properties: &WalletProperties) -> Result<()>;
    fn initialize_bdk_wallet(&self) -> Result<ChangeSet>;
    fn store_bdk_wallet_changeset(&self, changeset: &ChangeSet) -> Result<()>;
    fn read_properties(&self) -> Result<Option<WalletProperties>>;
    fn check_recipient_exists(&self, recipient: &str) -> Result<bool>;
    fn create_new_movement(
        &self,
        status: MovementStatus,
        subsystem: &MovementSubsystem,
        time: DateTime<Local>,
    ) -> Result<MovementId>;
    fn update_movement(&self, movement: &Movement) -> Result<()>;
    fn get_movement_by_id(&self, movement_id: MovementId) -> Result<Movement>;
    fn get_all_movements(&self) -> Result<Vec<Movement>>;
    fn store_pending_board(
        &self,
        vtxo: &Vtxo,
        funding_tx: &Transaction,
        movement_id: MovementId,
    ) -> Result<()>;
    fn remove_pending_board(&self, vtxo_id: &VtxoId) -> Result<()>;
    fn get_all_pending_board_ids(&self) -> Result<Vec<VtxoId>>;
    fn get_pending_board_by_vtxo_id(
        &self,
        vtxo_id: VtxoId,
    ) -> Result<Option<PendingBoard>>;
    fn store_round_state_lock_vtxos(
        &self,
        round_state: &RoundState,
    ) -> Result<RoundStateId>;
    fn update_round_state(&self, round_state: &StoredRoundState) -> Result<()>;
    fn remove_round_state(&self, round_state: &StoredRoundState) -> Result<()>;
    fn load_round_states(&self) -> Result<Vec<StoredRoundState>>;
    fn store_recovered_round(&self, round: &UnconfirmedRound) -> Result<()>;
    fn remove_recovered_round(&self, funding_txid: Txid) -> Result<()>;
    fn load_recovered_rounds(&self) -> Result<Vec<UnconfirmedRound>>;
    fn store_vtxos(&self, vtxos: &[(&Vtxo, &VtxoState)]) -> Result<()>;
    fn get_wallet_vtxo(&self, id: VtxoId) -> Result<Option<WalletVtxo>>;
    fn get_all_vtxos(&self) -> Result<Vec<WalletVtxo>>;
    fn get_vtxos_by_state(
        &self,
        state: &[VtxoStateKind],
    ) -> Result<Vec<WalletVtxo>>;
    fn remove_vtxo(&self, id: VtxoId) -> Result<Option<Vtxo>>;
    fn has_spent_vtxo(&self, id: VtxoId) -> Result<bool>;
    fn store_vtxo_key(&self, index: u32, public_key: PublicKey) -> Result<()>;
    fn get_last_vtxo_key_index(&self) -> Result<Option<u32>>;
    fn get_public_key_idx(&self, public_key: &PublicKey) -> Result<Option<u32>>;
    fn store_new_pending_lightning_send(
        &self,
        invoice: &Invoice,
        amount: &Amount,
        vtxos: &[VtxoId],
        movement_id: MovementId,
    ) -> Result<LightningSend>;
    fn get_all_pending_lightning_send(&self) -> Result<Vec<LightningSend>>;
    fn finish_lightning_send(
        &self,
        payment_hash: PaymentHash,
        preimage: Option<Preimage>,
    ) -> Result<()>;
    fn remove_lightning_send(&self, payment_hash: PaymentHash) -> Result<()>;
    fn get_lightning_send(
        &self,
        payment_hash: PaymentHash,
    ) -> Result<Option<LightningSend>>;
    fn store_lightning_receive(
        &self,
        payment_hash: PaymentHash,
        preimage: Preimage,
        invoice: &Bolt11Invoice,
        htlc_recv_cltv_delta: BlockDelta,
    ) -> Result<()>;
    fn get_all_pending_lightning_receives(
        &self,
    ) -> Result<Vec<LightningReceive>>;
    fn set_preimage_revealed(&self, payment_hash: PaymentHash) -> Result<()>;
    fn update_lightning_receive(
        &self,
        payment_hash: PaymentHash,
        htlc_vtxo_ids: &[VtxoId],
        movement_id: MovementId,
    ) -> Result<()>;
    fn fetch_lightning_receive_by_payment_hash(
        &self,
        payment_hash: PaymentHash,
    ) -> Result<Option<LightningReceive>>;
    fn finish_pending_lightning_receive(
        &self,
        payment_hash: PaymentHash,
    ) -> Result<()>;
    fn store_exit_vtxo_entry(&self, exit: &StoredExit) -> Result<()>;
    fn remove_exit_vtxo_entry(&self, id: &VtxoId) -> Result<()>;
    fn get_exit_vtxo_entries(&self) -> Result<Vec<StoredExit>>;
    fn store_exit_child_tx(
        &self,
        exit_txid: Txid,
        child_tx: &Transaction,
        origin: ExitTxOrigin,
    ) -> Result<()>;
    fn get_exit_child_tx(
        &self,
        exit_txid: Txid,
    ) -> Result<Option<(Transaction, ExitTxOrigin)>>;
    fn update_vtxo_state_checked(
        &self,
        vtxo_id: VtxoId,
        new_state: VtxoState,
        allowed_old_states: &[VtxoStateKind],
    ) -> Result<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.

Required Methods

fn init_wallet(&self, properties: &WalletProperties) -> Result<()>

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.

fn initialize_bdk_wallet(&self) -> Result<ChangeSet>

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.

fn store_bdk_wallet_changeset(&self, changeset: &ChangeSet) -> Result<()>

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.

fn read_properties(&self) -> Result<Option<WalletProperties>>

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.

fn check_recipient_exists(&self, recipient: &str) -> Result<bool>

Check whether a recipient identifier already exists.

Useful to avoid storing duplicate recipients for the same logical payee or duplicated lightning invoice payments (unsafe)

Parameters:

• recipient: A recipient identifier (e.g., invoice).

Returns:

• Ok(true) if the recipient exists,
• Ok(false) otherwise.

Errors:

• Returns an error if the lookup fails.

fn create_new_movement( &self, status: MovementStatus, subsystem: &MovementSubsystem, time: DateTime<Local>, ) -> Result<MovementId>

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.

fn update_movement(&self, movement: &Movement) -> Result<()>

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.

fn get_movement_by_id(&self, movement_id: MovementId) -> Result<Movement>

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.

fn get_all_movements(&self) -> Result<Vec<Movement>>

Gets every stored movement.

Returns:

• Ok(Vec<Movement>) containing all movements, empty if none exist.

Errors:

• If retrieving the movements fails.

fn store_pending_board( &self, vtxo: &Vtxo, funding_tx: &Transaction, movement_id: MovementId, ) -> Result<()>

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.

fn remove_pending_board(&self, vtxo_id: &VtxoId) -> Result<()>

Remove a pending board.

Parameters:

• vtxo_id: The VtxoId to remove.

Errors:

• Returns an error if the board cannot be removed.

fn get_all_pending_board_ids(&self) -> Result<Vec<VtxoId>>

Get the VtxoId for each pending board.

Returns:

• Ok(Vec<VtxoId>) possibly empty.

Errors:

• Returns an error if the query fails.

fn get_pending_board_by_vtxo_id( &self, vtxo_id: VtxoId, ) -> Result<Option<PendingBoard>>

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.

fn store_round_state_lock_vtxos( &self, round_state: &RoundState, ) -> Result<RoundStateId>

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

fn update_round_state(&self, round_state: &StoredRoundState) -> Result<()>

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

fn remove_round_state(&self, round_state: &StoredRoundState) -> 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

fn load_round_states(&self) -> Result<Vec<StoredRoundState>>

Load all pending round states from the db

Returns:

• Vec<StoredRoundState>: unordered vector with all stored round states

Errors:

• returns an error of the states could not be succesfully retrieved

fn store_recovered_round(&self, round: &UnconfirmedRound) -> Result<()>

Store a recovered past round

fn remove_recovered_round(&self, funding_txid: Txid) -> Result<()>

Remove a recovered past round

fn load_recovered_rounds(&self) -> Result<Vec<UnconfirmedRound>>

Load the recovered past rounds

fn store_vtxos(&self, vtxos: &[(&Vtxo, &VtxoState)]) -> Result<()>

Stores the given VTXOs in the given VtxoState.

fn get_wallet_vtxo(&self, id: VtxoId) -> Result<Option<WalletVtxo>>

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.

fn get_all_vtxos(&self) -> Result<Vec<WalletVtxo>>

Fetch all wallet VTXOs in the database.

Returns:

• Ok(Vec<WalletVtxo>) possibly empty.

Errors:

• Returns an error if the query fails.

fn get_vtxos_by_state(&self, state: &[VtxoStateKind]) -> 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.

fn remove_vtxo(&self, id: VtxoId) -> Result<Option<Vtxo>>

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.

fn has_spent_vtxo(&self, id: VtxoId) -> Result<bool>

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.

fn store_vtxo_key(&self, index: u32, public_key: PublicKey) -> Result<()>

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.

fn get_last_vtxo_key_index(&self) -> Result<Option<u32>>

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.

fn get_public_key_idx(&self, public_key: &PublicKey) -> 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.

fn store_new_pending_lightning_send( &self, invoice: &Invoice, amount: &Amount, vtxos: &[VtxoId], movement_id: MovementId, ) -> Result<LightningSend>

Store a new pending lightning send.

Parameters:

• invoice: The invoice of the pending lightning send.
• amount: The amount of the pending lightning send.
• vtxos: The vtxos of the pending lightning send.

Errors:

• Returns an error if the pending lightning send cannot be stored.

fn get_all_pending_lightning_send(&self) -> Result<Vec<LightningSend>>

Get all pending lightning sends.

Returns:

• Ok(Vec<LightningSend>) possibly empty.

Errors:

• Returns an error if the query fails.

fn finish_lightning_send( &self, payment_hash: PaymentHash, preimage: Option<Preimage>, ) -> Result<()>

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.

fn remove_lightning_send(&self, payment_hash: PaymentHash) -> 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.

fn get_lightning_send( &self, payment_hash: PaymentHash, ) -> Result<Option<LightningSend>>

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.

fn store_lightning_receive( &self, payment_hash: PaymentHash, preimage: Preimage, invoice: &Bolt11Invoice, htlc_recv_cltv_delta: BlockDelta, ) -> Result<()>

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.

fn get_all_pending_lightning_receives(&self) -> Result<Vec<LightningReceive>>

Returns a list of all pending lightning receives

Returns:

• Ok(Vec<LightningReceive>) possibly empty.

Errors:

• Returns an error if the query fails.

fn set_preimage_revealed(&self, payment_hash: PaymentHash) -> Result<()>

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.

fn update_lightning_receive( &self, payment_hash: PaymentHash, htlc_vtxo_ids: &[VtxoId], movement_id: MovementId, ) -> 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.

fn fetch_lightning_receive_by_payment_hash( &self, payment_hash: PaymentHash, ) -> Result<Option<LightningReceive>>

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.

fn finish_pending_lightning_receive( &self, payment_hash: PaymentHash, ) -> Result<()>

Remove a Lightning receive by its payment hash.

Parameters:

• payment_hash: The payment hash of the record to remove.

Errors:

• Returns an error if the removal fails.

fn store_exit_vtxo_entry(&self, exit: &StoredExit) -> 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.

fn remove_exit_vtxo_entry(&self, id: &VtxoId) -> 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.

fn get_exit_vtxo_entries(&self) -> Result<Vec<StoredExit>>

List all VTXOs currently tracked as being exited.

Returns:

• Ok(Vec<StoredExit>) possibly empty.

Errors:

• Returns an error if the query fails.

fn store_exit_child_tx( &self, exit_txid: Txid, child_tx: &Transaction, origin: ExitTxOrigin, ) -> Result<()>

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.

fn get_exit_child_tx( &self, exit_txid: Txid, ) -> Result<Option<(Transaction, ExitTxOrigin)>>

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.

fn update_vtxo_state_checked( &self, vtxo_id: VtxoId, new_state: VtxoState, allowed_old_states: &[VtxoStateKind], ) -> Result<WalletVtxo>

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.

Implementors

impl BarkPersister for SqliteClient