Struct Client 

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

A client to interact with Ark server

See OfflineClient docs for details.

Implementations

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

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

pub fn start_vtxo_watcher( self: &Arc<Self>, delegator: Arc<DelegatorClient>, config: VtxoWatcherConfig, ) -> VtxoWatcherHandle

Start a background task that watches for new VTXOs and:

1. Delegates them to the configured delegator service for future auto-renewal
2. Self-renews VTXOs that are close to expiry (safety net)
3. Migrates funds off deprecated server signers on a periodic, backed-off pass (unless disabled via VtxoWatcherConfig::migrate_deprecated_signers)

Reconnects automatically with exponential backoff (1s → 2s → … → 30s) on stream errors.

Requires the client to be wrapped in an Arc for shared ownership with the background task.

Returns a VtxoWatcherHandle that stops the watcher when dropped.

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

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

pub async fn issue_asset( &self, amount: u64, control_asset_config: Option<ControlAssetConfig>, metadata: Option<Vec<(String, String)>>, ) -> Result<IssueAssetResult, Error>

Issue a new asset.

Creates a fresh asset with the given amount. The asset is sent to the caller’s own address. If control_asset is provided, the asset can be reissued in the future.

pub async fn reissue_asset( &self, asset_id: AssetId, amount: u64, ) -> Result<Txid, Error>

Reissue additional units of an existing asset.

The asset must have been created with a control asset. The control asset is spent as input and sent back to the caller, while the new asset units are minted.

pub async fn burn_asset( &self, asset_id: AssetId, amount: u64, ) -> Result<Txid, Error>

Burn a specific amount of an asset.

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_all<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.

Most callers should prefer Self::settle, which only renews VTXOs that have actually expired. Settling unexpired VTXOs is rarely necessary.

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

where R: Rng + CryptoRng + Clone,

Settle prior VTXOs that have expired or are recoverable, together with all available boarding outputs, into the next batch, generating new confirmed VTXOs.

Healthy (unexpired) VTXOs are left untouched. This is the path callers typically want when periodically renewing their wallet: healthy VTXOs do not need to be touched, and including them would only inflate batch fees. Boarding outputs are always included because callers generally want freshly funded coins to enter the Ark.

NOTE: sub-dust recoverable VTXOs can only be rescued when their combined value exceeds the server’s dust threshold; otherwise the batch protocol rejects the settlement with a cannot settle into sub-dust VTXO error. When the wallet holds isolated sub-dust amounts, fall back to Self::settle_all, which can roll them in alongside healthy VTXOs that act as carrier value.

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<[u8; 32], 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. When Boltz claims the VHTLC, the preimage is revealed in the claim transaction’s witness. This method extracts and persists the preimage to swap storage.

Returns

The 32-byte preimage that was revealed when Boltz claimed the VHTLC.

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

Extract the preimage from a claimed submarine swap VHTLC.

After Boltz claims the VHTLC, the preimage is embedded in the claim transaction’s PSBT via the VTXO_CONDITION_KEY unknown field. This method fetches that transaction and extracts the preimage.

The extracted preimage is validated against the stored preimage hash and persisted to swap storage.

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>, description: Option<String>, ) -> 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.
• expiry_secs: optional invoice expiry, in seconds from now. If None, Boltz’s default is used.
• description: optional memo embedded in the BOLT11 invoice’s d field (visible to the payer).

Returns

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

pub async fn get_ln_invoice_for_address( &self, amount: SwapAmount, recipient_address: ArkAddress, expiry_secs: Option<u64>, description: Option<String>, ) -> Result<ReverseSwapResult, Error>

Generate a BOLT11 invoice to receive Lightning into another user’s Arkade address.

The local client still creates and claims the Boltz reverse-swap VHTLC, but the resulting Ark output is sent to recipient_address instead of a fresh local address.

Arguments

• amount: the expected Amount to be received.
• recipient_address: Arkade address that receives the claimed VHTLC output.
• expiry_secs: optional invoice expiry, in seconds from now. If None, Boltz’s default is used.
• description: optional memo embedded in the BOLT11 invoice’s d field (visible to the payer).

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, description: Option<String>, ) -> 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.
• expiry_secs: optional invoice expiry, in seconds from now. If None, Boltz’s default is used.
• 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.
• description: optional memo embedded in the BOLT11 invoice’s d field (visible to the payer).

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 get_ln_invoice_from_hash_for_address( &self, amount: SwapAmount, recipient_address: ArkAddress, expiry_secs: Option<u64>, preimage_hash_sha256: Hash, description: Option<String>, ) -> Result<ReverseSwapResult, Error>

Generate a BOLT11 invoice from an externally managed preimage hash and receive the claimed VHTLC output into another user’s Arkade address.

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 create_chain_swap( &self, direction: ChainSwapDirection, amount: ChainSwapAmount, ) -> Result<ChainSwapResult, Error>

Create a chain swap via Boltz for swapping between ARK and on-chain BTC.

Returns a ChainSwapResult containing the swap ID and the address the user must fund to initiate the swap. For ChainSwapDirection::ArkToBtc, the user should send Ark VTXOs to the user_lockup_address using [Client::send_vtxo]. For ChainSwapDirection::BtcToArk, the user should send BTC to the user_lockup_address.

After funding, use Self::wait_for_chain_swap_server_lockup to wait for Boltz to lock their side, then Self::claim_chain_swap to claim.

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

Wait for Boltz to lock funds on their side of the chain swap.

Returns when the server’s lockup transaction is detected in the mempool or confirmed. After this returns, use Self::claim_chain_swap to claim the funds.

Returns the server’s lockup transaction ID if available.

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

Claim the Ark VHTLC from a chain swap after Boltz has locked funds.

This claims the server’s Ark VHTLC lockup using the stored preimage. It is intended for ChainSwapDirection::BtcToArk swaps where the server locks an Ark VHTLC.

Call this after Self::wait_for_chain_swap_server_lockup returns.

pub async fn claim_chain_swap_btc( &self, swap_id: &str, destination_address: Address, fee_rate_sat_vb: f64, ) -> Result<Txid, Error>

Claim on-chain BTC from a chain swap after Boltz has locked funds.

This claims the server’s on-chain BTC HTLC using the stored preimage. It is intended for ChainSwapDirection::ArkToBtc swaps where the server locks on-chain BTC.

Call this after Self::wait_for_chain_swap_server_lockup returns.

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

Refund the Ark VHTLC from a chain swap after the timelock has expired.

This is for ChainSwapDirection::ArkToBtc swaps where the user locked an Ark VHTLC and needs to reclaim it (e.g. if Boltz never locked BTC or the swap expired).

This path does not require a signature from Boltz.

pub async fn refund_chain_swap_btc( &self, swap_id: &str, destination_address: Address, fee_rate_sat_vb: f64, ) -> Result<Txid, Error>

Refund on-chain BTC from a chain swap after the timelock has expired.

This is for ChainSwapDirection::BtcToArk swaps where the user locked on-chain BTC and needs to reclaim it (e.g. if Boltz never locked the Ark VHTLC or the swap expired).

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

Query the current status of any Boltz swap by ID.

Checks local swap storage to determine the swap type, then queries the Boltz API for the live status.

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.

pub async fn list_pending_vhtlc_spend_txs( &self, ) -> Result<Vec<PendingVhtlcSpendTx>, Error>

List pending (submitted but not finalized) VHTLC spend transactions.

This checks all non-terminal swaps in storage, queries the server for pending VTXOs on their VHTLC addresses, and determines the spend type from the PSBT data.

pub async fn continue_pending_vhtlc_spend_tx( &self, pending: &PendingVhtlcSpendTx, ) -> Result<Txid, Error>

Continue (finalize) a pending VHTLC spend transaction.

Handles the different spend types appropriately:

• Claim: signs the checkpoint with the claim key and injects the preimage.
• CollaborativeRefund: re-requests Boltz’s signature, then signs with the refund key.
• ExpiredRefund: signs the checkpoint with the refund key (no Boltz needed).

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

Sign and finalize all pending VHTLC spend 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 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 migrate_deprecated_signer_vtxos<R>( &self, rng: &mut R, ) -> Result<DeprecatedSignerMigrationReport, Error>

where R: Rng + CryptoRng + Clone,

Sweep VTXOs and boarding outputs minted under a pre-cutoff deprecated server signer to the current signer, then report what moved.

Only deprecated-signer, pre-cutoff inputs are touched — current-signer outputs are left untouched (no consolidation, no incidental settlement fee), and past-cutoff outputs are skipped automatically by Self::fetch_commitment_transaction_inputs (the operator won’t co-sign the old key, so they become recoverable after expiry and exit via the recovery path).

Migration runs as two independent legs — a VTXO leg and a boarding leg — each routed through Self::settle_vtxos with its own scoped outpoint set. A failure in one leg does not suppress the other. Before settling, each leg is sized against the server’s per-output ceiling (vtxo_max_amount) and dust floor (see MigrationLegReport for the exact pipeline): inputs that individually exceed the ceiling are reported as oversized (they can never form a <= ceiling output and must exit unilaterally — they are NOT silently dropped); the remainder is selected highest-value-first up to MAX_VTXOS_PER_SETTLEMENT and a running aggregate within the ceiling, deferring the rest to a later cycle; a leg whose selected aggregate is below dust is skipped.

When the server advertises no deprecated signers, returns an empty MigrationSkipReason::NothingMigratable report without touching the wallet.

pub async fn deprecated_signer_status( &self, ) -> Result<Vec<DeprecatedSignerReport>, Error>

Report the per-signer status of every deprecated server signer the wallet currently holds funds under, without migrating anything.

This is observability only — it never moves funds and never calls settle or migrate. It is the read-only sibling of Self::migrate_deprecated_signer_vtxos. For each deprecated signer it merges the wallet’s VTXO holdings (resolved via the script -> VTXO map, like Self::offchain_balance) and its on-chain boarding holdings (grouped by [BoardingOutput::server_pk]) into one DeprecatedSignerReport.

Signers under which the wallet holds neither VTXOs nor boarding outputs are omitted. When the server advertises no deprecated signers, returns an empty vector without touching the chain.

For DeprecatedSignerStatus::Expired signers the VTXOs are additionally split into the already-swept/expired recoverable_* set and the not-yet-swept awaiting_sweep_* set, and next_sweep_eta is the soonest VTXO expiry (expires_at) among the awaiting set.

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(&self, receivers: Vec<SendReceiver>) -> Result<Txid, Error>

Send bitcoin and/or Arkade assets offchain to one or more receivers.

Coin selection handles both bitcoin-only and asset-bearing VTXOs. An asset packet is attached only when the transfer actually involves carried or requested assets.

Arguments

• receivers - a list of SendReceivers, specifying a target address, a bitcoin amount and an optional list of assets.

Returns

The Txid of the resulting Ark transaction.

pub async fn send_selection( &self, vtxo_outpoints: &[OutPoint], receivers: Vec<SendReceiver>, ) -> Result<Txid, Error>

Spend specific VTXOs in an Ark transaction sending bitcoin and/or Arkade assets to one or more receivers.

Unlike Self::send, 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 - a list of all the outpoints to be used as inputs to the transaction.
• receivers - a list of SendReceivers, specifying a target address, a bitcoin amount and an optional list of assets.

Returns

The Txid of the generated Ark transaction.

Errors

Returns an error if the selected VTXOs don’t have enough BTC value or assets to cover the requested receiver amounts.

pub async fn finalize_pending_offchain_tx( &self, ark_txid: Txid, ) -> Result<(), Error>

Finalize a specific pending offchain transaction.

Fetches the pending transaction identified by ark_txid from the server, signs the checkpoint transactions, and finalizes it.

This is useful when you need fine-grained control over which pending transaction to finalize (e.g. when a database tracks individual pending funding attempts).

Errors

Returns an error if no pending transaction with the given ark_txid is found, or if signing / finalization fails.

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.

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 submit_offchain_tx( &self, vtxo_inputs: Vec<VtxoInput>, address: ArkAddress, amount: Amount, ) -> Result<Txid, Error>

Build, sign and submit an offchain transaction to the server without finalizing.

This is primarily useful for testing pending transaction recovery flows.

Returns the Ark TXID. The transaction will remain in a pending state on the server until Self::finalize_pending_offchain_tx or Self::continue_pending_offchain_txs completes it.

pub async fn finalize_offchain_tx( &self, ark_txid: Txid, signed_checkpoint_txs: Vec<Psbt>, ) -> Result<(), Error>

Submit offchain transaction data for finalization.

We retry a few times to overcome transient failures.

After submit succeeds but before finalize completes, a transient error would leave the transaction in a pending state. Retrying here attempts to resolve that, without needing full recovery via Self::continue_pending_offchain_txs.

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 a commitment transaction output to a spendable VTXO. Every transaction is finalized, 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 server_info(&self) -> Result<Info, Error>

Returns the latest cached Ark server info.

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

Refresh cached /info data.

Useful after an out-of-band server restart or signer rotation, and also used by guarded RPC clients after arkd reports stale client state.

The refreshed snapshot includes the server’s current server::Info::deprecated_signers. The background watcher’s migration arm then observes those freshly advertised deprecated signers on its next pass and rotates funds off them via Self::migrate_deprecated_signer_vtxos.

pub fn delegator_pk(&self) -> Option<XOnlyPublicKey>

Returns the currently configured delegator pubkey, if any.

pub fn boltz_referral_id(&self) -> Option<&str>

Returns the Boltz referral ID sent with all swap creation requests, if any.

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

Get a new offchain receiving address.

When a delegator is configured (via delegator_pk passed to OfflineClient::new), returns a 3-leaf delegate address. Otherwise returns a standard 2-leaf 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>

Get all known offchain addresses for this wallet.

When a delegator is configured, this returns both the default (2-leaf) and delegate (3-leaf) addresses for each key, so that VTXOs at either address are visible. If historical delegator keys are set via historical_delegator_pks passed to OfflineClient::new, addresses for those are included too.

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 list_vtxos_for_outpoints( &self, outpoints: Vec<OutPoint>, ) -> Result<(VtxoList, HashMap<ScriptBuf, Vtxo>), 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 get_asset(&self, asset_id: AssetId) -> Result<AssetInfo, Error>

Get information about an asset by its ID.

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

pub fn dust(&self) -> Result<Amount, Error>

The server’s dust threshold amount.

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