Struct Client 

pub struct Client<B, W, S, K> {
    pub server_info: Info,
    /* private fields */
}

A client to interact with Ark server

See OfflineClient docs for details.

Fields

server_info: Info

Implementations

impl<B, W, S, K> Client<B, W, S, K>

where B: Blockchain, W: BoardingWallet + OnchainWallet, S: SwapStorage + 'static, K: KeyProvider,

pub async fn settle<R>(&self, rng: &mut R) -> Result<Option<Txid>, Error>

where R: Rng + CryptoRng + Clone,

Settle all prior VTXOs and boarding outputs into the next batch, generating new confirmed VTXOs.

pub async fn settle_with_notes<R>( &self, rng: &mut R, notes: Vec<ArkNote>, ) -> Result<Option<Txid>, Error>

where R: Rng + CryptoRng + Clone,

Settle all prior VTXOs, boarding outputs, and the provided ArkNotes into the next batch.

ArkNotes are bearer tokens that can be redeemed by revealing their preimage. This method combines them with regular VTXOs and boarding outputs into a single settlement transaction.

pub async fn settle_vtxos<R>( &self, rng: &mut R, vtxo_outpoints: &[OutPoint], boarding_outpoints: &[OutPoint], ) -> Result<Option<Txid>, Error>

where R: Rng + CryptoRng + Clone,

Settle specific VTXOs and boarding outputs by outpoint into the next batch, generating new confirmed VTXOs.

Unlike Self::settle, this method allows the caller to specify exactly which VTXOs and boarding outputs to settle by providing their outpoints.

pub async fn collaborative_redeem<R>( &self, rng: &mut R, to_address: Address, to_amount: Amount, ) -> Result<Txid, Error>

where R: Rng + CryptoRng + Clone,

Settle some prior VTXOs and boarding outputs into the next batch, generating UTXOs as outputs to a new commitment transaction.

pub async fn collaborative_redeem_vtxo_selection<R>( &self, rng: &mut R, input_vtxos: impl Iterator<Item = OutPoint> + Clone, to_address: Address, to_amount: Amount, ) -> Result<Txid, Error>

where R: Rng + CryptoRng + Clone,

Settle a selection of VTXOs into the next batch, generating UTXOs as outputs to a new commitment transaction.

pub async fn generate_delegate( &self, delegate_cosigner_pk: PublicKey, ) -> Result<Delegate, Error>

Generate a delegate for settling VTXOs on behalf of the owner.

The owner pre-signs the intent and forfeit transactions, allowing another party to complete the settlement at a later time using the provided delegate_cosigner_pk.

Arguments

• delegate_cosigner_pk - The cosigner public key that the delegate will use
• select_recoverable_vtxos - Whether to include recoverable VTXOs

Returns

A Delegate struct containing all the pre-signed data needed for settlement.

pub fn sign_delegate_psbts( &self, intent_psbt: &mut Psbt, forfeit_psbts: &mut [Psbt], ) -> Result<(), Error>

Sign a set of delegate PSBTs, including the intent PSBT and the forfeit PSBTs.

pub async fn settle_delegate<R>( &self, rng: &mut R, delegate: Delegate, own_cosigner_kp: Keypair, ) -> Result<Txid, Error>

where R: Rng + CryptoRng,

Settle a delegate by completing the batch protocol using pre-signed data.

This method allows Bob to settle Alice’s VTXOs using the pre-signed intent and forfeit transactions from the Delegate struct.

Arguments

• rng - Random number generator for nonce generation
• delegate - The delegate struct containing pre-signed data
• own_cosigner_kp - Bob’s cosigner keypair (must match the delegate_cosigner_pk)

Returns

The commitment transaction ID if successful.

impl<B, W, S, K> Client<B, W, S, K>

where B: Blockchain, W: BoardingWallet + OnchainWallet, S: SwapStorage + 'static, K: KeyProvider,

pub async fn prepare_ln_invoice_payment( &self, invoice: Bolt11Invoice, ) -> Result<SubmarineSwapData, Error>

Prepare the payment of a BOLT11 invoice by setting up a submarine swap via Boltz.

This function does not execute the payment itself. Once you are ready for payment you will have to send the required amount to the vhtlc_address.

If you are looking for a function which pays the invoice immediately, consider using Client::pay_ln_invoice instead.

Arguments

• invoice: a Bolt11Invoice to be paid.

Returns

• A SubmarineSwapData object, including an identifier for the swap.

pub async fn pay_ln_invoice( &self, invoice: Bolt11Invoice, ) -> Result<SubmarineSwapResult, Error>

Pay a BOLT11 invoice by performing a submarine swap via Boltz. This allows to make Lightning payments with an Ark wallet.

Arguments

• invoice: a Bolt11Invoice to be paid.

Returns

• A [SubmarineSwapResult], including an identifier for the swap and the TXID of the Ark transaction that funds the VHTLC.

pub async fn wait_for_invoice_paid(&self, swap_id: &str) -> Result<(), Error>

Wait for the Lightning invoice associated with a submarine swap to be paid by Boltz.

Boltz will first need to claim our VHTLC before paying the invoice.

pub async fn refund_expired_vhtlc(&self, swap_id: &str) -> Result<Txid, Error>

Refund a VHTLC after the timelock has expired.

This path does not require a signature from Boltz.

pub async fn refund_expired_vhtlc_via_settlement<R>( &self, rng: &mut R, swap_id: &str, ) -> Result<Txid, Error>

where R: Rng + CryptoRng,

Refund a VHTLC after the timelock has expired via settlement.

This path does not require a signature from Boltz.

pub async fn refund_vhtlc(&self, swap_id: &str) -> Result<Txid, Error>

Refund a VHTLC with collaboration from Boltz.

This path requires Boltz’s cooperation to sign the refund transaction. It allows refunding a submarine swap before the timelock expires. For refunds after timelock expiry without Boltz cooperation, use Client::refund_expired_vhtlc instead.

pub async fn get_ln_invoice( &self, amount: SwapAmount, expiry_secs: Option<u64>, ) -> Result<ReverseSwapResult, Error>

Generate a BOLT11 invoice to perform a reverse submarine swap via Boltz. This allows to receive Lightning payments into an Ark wallet.

Arguments

• amount: the expected Amount to be received.

Returns

• A ReverseSwapResult, including an identifier for the reverse swap and the Bolt11Invoice to be paid.

pub async fn get_ln_invoice_from_hash( &self, amount: SwapAmount, expiry_secs: Option<u64>, preimage_hash_sha256: Hash, ) -> Result<ReverseSwapResult, Error>

Generate a BOLT11 invoice using a provided SHA256 preimage hash for a reverse submarine swap via Boltz. This allows receiving Lightning payments when the preimage is managed externally.

Arguments

• amount: the expected Amount to be received.
• preimage_hash_sha256: the SHA256 hash of the preimage. The preimage itself is not stored and must be provided later when claiming via Self::claim_vhtlc.

Returns

• A [ReverseSwapResult], including an identifier for the reverse swap and the Bolt11Invoice to be paid.

Note

After calling this method, use Self::wait_for_vhtlc_funding to wait for the VHTLC to be funded, then Self::claim_vhtlc with the preimage to claim the funds.

pub async fn wait_for_vhtlc_funding(&self, swap_id: &str) -> Result<(), Error>

Wait for the VHTLC associated with a reverse submarine swap to be funded.

This method only waits for the funding transaction to be detected (in mempool or confirmed). It does not claim the VHTLC. Use Self::claim_vhtlc to claim after the preimage is known.

Arguments

• swap_id: The unique identifier for the reverse swap.

Returns

Returns Ok(()) when the VHTLC funding transaction is detected.

pub async fn claim_vhtlc( &self, swap_id: &str, preimage: [u8; 32], ) -> Result<ClaimVhtlcResult, Error>

Claim a funded VHTLC for a reverse submarine swap using the preimage.

This method should be called after the VHTLC has been funded (after Self::wait_for_vhtlc_funding returns) and the preimage is known.

Arguments

• swap_id: The unique identifier for the reverse swap.
• preimage: The 32-byte preimage that unlocks the VHTLC.

Returns

Returns a [ClaimVhtlcResult] with details about the claim transaction.

pub async fn wait_for_vhtlc( &self, swap_id: &str, ) -> Result<ClaimVhtlcResult, Error>

Wait for the VHTLC associated with a reverse submarine swap to be funded, then claim it.

Note

This method requires that the preimage was stored when creating the reverse swap (i.e., via Self::get_ln_invoice). If the swap was created with Self::get_ln_invoice_from_hash, use Self::wait_for_vhtlc_funding followed by Self::claim_vhtlc instead.

pub async fn get_fees(&self) -> Result<BoltzFees, Error>

Fetch fee information from Boltz for both submarine and reverse swaps.

Returns

• A [BoltzFees] struct containing fee information for both swap types.

pub async fn get_limits(&self) -> Result<SwapLimits, Error>

Fetch swap amount limits from Boltz for submarine swaps.

Returns

• A [SwapLimits] struct containing minimum and maximum swap amounts in satoshis.

pub fn subscribe_to_swap_updates( &self, swap_id: String, ) -> impl Stream<Item = Result<SwapStatus, Error>> + '_

Use Boltz’s API to learn about updates for a particular swap.

impl<B, W, S, K> Client<B, W, S, K>

where B: Blockchain, W: BoardingWallet + OnchainWallet, S: SwapStorage + 'static, K: KeyProvider,

pub async fn estimate_onchain_fees<R>( &self, rng: &mut R, to_address: Address, to_amount: Amount, ) -> Result<SignedAmount, Error>

where R: Rng + CryptoRng + Clone,

Estimates the fee to collaboratively redeem VTXOs to an on-chain Bitcoin address.

This function calculates the expected fee for moving funds from the Ark protocol back to a standard on-chain Bitcoin address through a collaborative redemption process. The fee is estimated by creating a simulated intent and querying the Ark server.

Arguments

• rng - A random number generator for creating the intent
• to_address - The on-chain Bitcoin address to send funds to
• to_amount - The amount to send to the destination address

Returns

Returns the estimated fee as a SignedAmount. The fee will be deducted from the total available balance when performing the actual redemption.

Errors

Returns an error if:

• The available balance is insufficient for the requested amount
• Failed to fetch VTXOs or boarding inputs
• Failed to communicate with the Ark server

pub async fn estimate_batch_fees<R>( &self, rng: &mut R, to_address: ArkAddress, ) -> Result<SignedAmount, Error>

where R: Rng + CryptoRng + Clone,

Estimates the fee to join the next batch and settle funds to an Ark address.

This function calculates the expected fee for consolidating all available VTXOs and boarding outputs into fresh VTXOs through the Ark batch process. The full available balance will be used, with fees deducted from the resulting VTXO.

Use this to estimate fees before calling settle or similar batch operations.

Arguments

• rng - A random number generator for creating the intent
• to_address - The Ark address to receive the settled funds

Returns

Returns the estimated fee as a SignedAmount. This fee will be deducted from the total available balance when joining the actual batch.

Errors

Returns an error if:

• Failed to fetch VTXOs or boarding inputs
• Failed to communicate with the Ark server

pub async fn estimate_onchain_fees_vtxo_selection<R>( &self, rng: &mut R, input_vtxos: impl Iterator<Item = OutPoint> + Clone, to_address: Address, to_amount: Amount, ) -> Result<SignedAmount, Error>

where R: Rng + CryptoRng + Clone,

Estimates the fee to collaboratively redeem specific VTXOs to an on-chain Bitcoin address.

This function is similar to estimate_onchain_fees, but allows you to specify exactly which VTXOs to use as inputs instead of using automatic coin selection. This is useful when you want to estimate fees for redeeming specific UTXOs.

Arguments

• rng - A random number generator for creating the intent
• input_vtxos - An iterator of OutPoints specifying which VTXOs to use as inputs
• to_address - The on-chain Bitcoin address to send funds to
• to_amount - The amount to send to the destination address

Returns

Returns the estimated fee as a SignedAmount. The fee will be deducted from the total input amount, with any remainder going to change.

Errors

Returns an error if:

• No matching VTXO outpoints are found
• The total input amount is insufficient for the requested amount plus fees
• Failed to fetch VTXOs
• Failed to communicate with the Ark server

pub async fn estimate_batch_fees_vtxo_selection<R>( &self, rng: &mut R, input_vtxos: impl Iterator<Item = OutPoint> + Clone, to_address: ArkAddress, ) -> Result<SignedAmount, Error>

where R: Rng + CryptoRng + Clone,

Estimates the fee to join the next batch with specific VTXOs and settle to an Ark address.

This function is similar to estimate_batch_fees, but allows you to specify exactly which VTXOs to use as inputs instead of using all available VTXOs. This is useful when you want to estimate fees for settling specific UTXOs into fresh VTXOs.

Arguments

• rng - A random number generator for creating the intent
• input_vtxos - An iterator of OutPoints specifying which VTXOs to use as inputs
• to_address - The Ark address to receive the settled funds

Returns

Returns the estimated fee as a SignedAmount. The fee will be deducted from the total input amount when joining the actual batch.

Errors

Returns an error if:

• No matching VTXO outpoints are found
• Failed to fetch VTXOs
• Failed to communicate with the Ark server

impl<B, W, S, K> Client<B, W, S, K>

where B: Blockchain, W: BoardingWallet + OnchainWallet, S: SwapStorage + 'static, K: KeyProvider,

pub async fn send_vtxo( &self, address: ArkAddress, amount: Amount, ) -> Result<Txid, Error>

Spend confirmed and pre-confirmed VTXOs in an Ark transaction sending the given amount to the given address.

The Ark transaction is built in collaboration with the Ark server. The outputs of said transaction will be pre-confirmed VTXOs.

Coin selection is performed automatically to choose which VTXOs to spend.

Returns

The Txid of the generated Ark transaction.

pub async fn send_vtxo_selection( &self, vtxo_outpoints: &[OutPoint], address: ArkAddress, amount: Amount, ) -> Result<Txid, Error>

Spend specific VTXOs in an Ark transaction sending the given amount to the given address.

The Ark transaction is built in collaboration with the Ark server. The outputs of said transaction will be pre-confirmed VTXOs.

Unlike Self::send_vtxo, this method allows the caller to specify exactly which VTXOs to spend by providing their outpoints. This is useful for applications that want to have full control over VTXO selection.

Arguments

• vtxo_outpoints - The specific VTXO outpoints to spend
• address - The destination Ark address
• amount - The amount to send

Returns

The Txid of the generated Ark transaction.

Errors

Returns an error if the selected VTXOs don’t have enough value to cover the requested amount.

pub async fn list_pending_offchain_txs(&self) -> Result<Vec<PendingTx>, Error>

List pending (submitted but not finalized) offchain transactions.

This retrieves any transactions that were submitted to the server but not yet finalized (e.g. due to a crash or network error between submit and finalize).

Returns

The pending transactions, or an empty vec if there are none.

pub async fn continue_pending_offchain_txs(&self) -> Result<Vec<Txid>, Error>

Resume and finalize any pending (submitted but not finalized) offchain transactions.

This handles the case where send_vtxo successfully submitted the transaction to the server but failed before finalizing (e.g. due to a crash or network error). The server holds the submitted-but-not-finalized transaction in a pending state. This method retrieves it, signs the checkpoint transactions, and finalizes.

Returns

The Txids of the finalized Ark transactions, or an empty vec if there were no pending transactions.

impl<B, W, S, K> Client<B, W, S, K>

where B: Blockchain, W: BoardingWallet + OnchainWallet, S: SwapStorage + 'static, K: KeyProvider,

pub async fn build_unilateral_exit_trees( &self, ) -> Result<Vec<Vec<Transaction>>, Error>

Build the unilateral exit transaction tree for all spendable VTXOs.

Returns

The tree as a Vec<Vec<Transaction>>, where each branch represents a path from commitment transaction output to a spendable VTXO. Every transaction is fully signed, but requires fee bumping through a P2A output.

pub async fn broadcast_next_unilateral_exit_node( &self, branch: &[Transaction], ) -> Result<Option<Txid>, Error>

Broadcast the next unconfirmed transaction in a branch, skipping transactions that are already on the blockchain.

Returns

Ok(Some(txid)) if a transaction was broadcast, Ok(None) if all are confirmed.

pub async fn send_on_chain( &self, to_address: Address, to_amount: Amount, ) -> Result<Txid, Error>

Spend boarding outputs and VTXOs to an on-chain address.

All these outputs are spent unilaterally.

To be able to spend a boarding output, we must wait for the exit delay to pass.

To be able to spend a VTXO, the VTXO itself must be published on-chain (via something like unilateral_off_board), and then we must wait for the exit delay to pass.

impl<B, W, S, K> Client<B, W, S, K>

where B: Blockchain, W: BoardingWallet + OnchainWallet, S: SwapStorage + 'static, K: KeyProvider,

pub fn get_offchain_address(&self) -> Result<(ArkAddress, Vtxo), Error>

Get a new offchain receiving address

For HD wallets, this will derive a new address each time it’s called. For static key providers, this will always return the same address.

pub fn get_offchain_addresses(&self) -> Result<Vec<(ArkAddress, Vtxo)>, Error>

pub async fn discover_keys(&self, gap_limit: u32) -> Result<u32, Error>

Discover and cache used keys using BIP44-style gap limit

This method derives keys in batches, checks all at once via list_vtxos, caches used ones, and stops when a full batch has no used keys.

Returns the number of discovered keys. No-op for StaticKeyProvider.

Arguments

• gap_limit - Number of consecutive unused addresses before stopping

pub fn get_boarding_address(&self) -> Result<Address, Error>

pub fn get_onchain_address(&self) -> Result<Address, Error>

pub fn get_boarding_addresses(&self) -> Result<Vec<Address>, Error>

pub async fn get_virtual_tx_outpoints( &self, addresses: impl Iterator<Item = ArkAddress>, ) -> Result<Vec<VirtualTxOutPoint>, Error>

pub async fn list_vtxos( &self, ) -> Result<(VtxoList, HashMap<ScriptBuf, Vtxo>), Error>

pub async fn list_vtxos_for_addresses( &self, addresses: impl Iterator<Item = ArkAddress>, ) -> Result<VtxoList, Error>

pub async fn get_vtxo_chain( &self, out_point: OutPoint, size: i32, index: i32, ) -> Result<Option<VtxoChainResponse>, Error>

pub async fn offchain_balance(&self) -> Result<OffChainBalance, Error>

pub async fn transaction_history(&self) -> Result<Vec<Transaction>, Error>

pub fn boarding_exit_delay_seconds(&self) -> u64

Get the boarding exit delay defined by the Ark server, in seconds.

Panics

This will panic if the boarding exit delay corresponds to a relative locktime specified in blocks. We expect the Ark server to use a relative locktime in seconds.

This will also panic if the sequence number returned by the server is not a valid relative locktime.

pub fn unilateral_vtxo_exit_delay_seconds(&self) -> u64

Get the unilateral exit delay for VTXOs defined by the Ark server, in seconds.

Panics

This will panic if the unilateral exit delay corresponds to a relative locktime specified in blocks. We expect the Ark server to use a relative locktime in seconds.

This will also panic if the sequence number returned by the server is not a valid relative locktime.

pub fn network_client(&self) -> Client

pub async fn bump_tx(&self, parent: &Transaction) -> Result<Transaction, Error>

Use the P2A output of a transaction to bump its transaction fee with a child transaction.

pub async fn subscribe_to_scripts( &self, scripts: Vec<ArkAddress>, subscription_id: Option<String>, ) -> Result<String, Error>

Subscribe to receive transaction notifications for specific VTXO scripts

This method allows you to subscribe to get notified about transactions affecting the provided VTXO addresses. It can also be used to update an existing subscription by adding new scripts to it.

Arguments

• scripts - Vector of ArkAddress to subscribe to
• subscription_id - Unique identifier for the subscription. Use the same ID to update an existing subscription. Use None for new subscriptions

Returns

Returns the subscription ID if successful

pub async fn unsubscribe_from_scripts( &self, scripts: Vec<ArkAddress>, subscription_id: String, ) -> Result<(), Error>

Remove scripts from an existing subscription

This method allows you to unsubscribe from receiving notifications for specific VTXO scripts while keeping the subscription active for other scripts.

Arguments

• scripts - Vector of ArkAddress to unsubscribe from
• subscription_id - The subscription ID to update

pub async fn get_subscription( &self, subscription_id: String, ) -> Result<impl Stream<Item = Result<SubscriptionResponse, Error>> + Unpin, Error>

Get a subscription stream that returns subscription responses

This method returns a stream that yields SubscriptionResponse messages containing information about new and spent VTXOs for the subscribed scripts.

Arguments

• subscription_id - The subscription ID to get the stream for

Returns

Returns a Stream of SubscriptionResponse messages