Skip to content

Advanced bark

There are two additional bark features that we don't expect most users will ever need to do, but that advanced users might want to try out:

  • Boarding: Taking on-chain bitcoin off-chain, onto an Ark.
  • Unilateral exit: Taking off-chain bitcoin on-chain, without any cooperation from the Ark server.

Boarding

We expect most users will receive their first sats over Ark directly, in the same way you received yours from our faucet. But it is definitely possible to move your on-chain funds into the Ark as well—we call it boarding!

Boarding is currently only possible from within bark's internal on-chain wallet. So for you to try it out, you need to have an on-chain balance.

Check your on-chain balance using: 

bark onchain balance

If you don't have any, our faucet can help you out. Grab an on-chain address from your bark wallet: 

bark onchain address
Then use the faucet to send some on-chain (signet) sats to this address.

You can use bark balance to double-check they've arrived.

Once you have some on-chain sats, you can board the Ark: 

# Board entire on-chain balance
bark board --all

# Board a specified amount
bark board "10000 sat"

After boarding, you should see that you now have a new VTXO with the type board: 

bark vtxos

You've successfully taken your on-chain bitcoin off-chain!

Unilateral exit

Finally, let's walk through performing a unilateral exit.

This process requires broadcasting multiple transactions sequentially, so please allocate 1-2 hours to complete this test.

Note

We're currently addressing some known issues with unilateral exits that may occur in certain edge cases. Let us know if you need help.

What you'll need

To get started, you will need the following:

  • At least one VTXO
  • At least 15,000 on-chain sats per VTXO you're exiting (just to be on the safe side!)
  • Make sure you have at least one confirmation each on-chain UTXO. Check this using bark onchain utxos or at mempool.space.
  • Patience

Under the hood

Each of your VTXOs consists of a series of off-chain transactions that must be broadcast to retrieve your sats on-chain.

The unilateral exit process will work as follows:

  • Each of the transactions in your unilateral exit will have to be broadcast and confirmed using a child-pays-for-parent transaction (CPFP).
  • Each child transaction has to wait an average of 10 minutes for its parent to confirm.
  • Once the final transaction of a VTXO's exit is confirmed, you will have to wait for a timelock to expire. The timelock is 12 blocks or about two hours.

Note

If you are using your own bitcoin node instead of the esplora backend, make sure the -txindex is enabled.

Performing the exit

First, you'll need to mark one or more VTXOs that you'd like to exit.

Mark a single VTXO for exit

bark exit start --vtxo <your_vtxo_id>

Mark multiple VTXOs for exit

bark exit start --vtxo <your_first_vtxo_id> --vtxo <your_second_vtxo_id>

Mark all VTXOs in your wallet for exit

bark exit start --all

Initiate your exits

Run the following command to begin the exit process:

bark exit progress --wait

Exits are a multi-step process, requiring multiple transactions broadcast in sequence, so the --wait flag ensures the operation will keep running until the entire VTXO has been exited. We'd recommend going to get a coffee while you wait!

Note

Be aware that you might see some scary logging, this does not necessarily mean that your exit will not succeed, often the process will automatically recover (e.g., retrying after an additional confirmation). If you really want to dig deeper, use the --verbose flag to follow everything that happens under the hood.

Claiming bitcoin from a completed exit

Once your exit has been completed—the leaf/exit transaction has been broadcast—your bitcoin is now on-chain and will not expire. However, spending this bitcoin still depends on the data held in your bark database. If you deleted your bark wallet data and had no backup other than a seed phrase, you would permanently lose access to the exited bitcoin.

To ensure your bitcoin is spendable with only your usual backup setup (e.g., a seed phrase), you'll need to spend the bitcoin to a separate on-chain wallet. This is called a claim and requires an additional on-chain transaction.

Don't worry though, bark makes claiming your exited bitcoin simple:

Get an on-chain address from your wallet

bark onchain address

Note

You don't have to use the bark's on-chain wallet, any on-chain wallet will suffice.

Claim unilateral exits using your on-chain address

bark exit claim <your_onchain_address> --vtxo <your_exited_vtxo_id>

When claiming an exit, you can either specify the --vtxo flag multiple times or just use the --all flag.

Checking the status of an exit

To check on the status of your exit(s), you can use one of the following commands:

bark exit list

bark exit status <your_vtxo_id>

Both commands support the --transactions and --history flags which can be extremely helpful when debugging issues.