Ramps: Boarding and Exiting

Ramps are the mechanisms that allow users with Bitcoin to onboard and exit from Arkade with its own built-in mechanisms. They are designed to provide a seamless experience for users, allowing them to move funds in and out of Arkade. There are two types of ramps: Boarding (onboarding) and Exiting (offboarding).

​

Boarding

Boarding is the process of swapping an onchain UTXO for an offchain VTXO. The preferred method for onboarding funds into Arkade is by sending Bitcoin to a boarding address.

​

1. Generate a boarding address

First, get a boarding address from your wallet. This is a specialized 2-of-2 multisig Taproot address.

// Get a boarding address
const boardingAddress = await wallet.getBoardingAddress()
console.log('Boarding Address:', boardingAddress)

​

2. Send Bitcoin to the boarding address

Send Bitcoin to this address using any standard Bitcoin wallet. This creates an onchain UTXO that will be used for boarding.

​

3. Check for boarding UTXOs and settle them to your wallet

Once the transaction is confirmed, check for available boarding UTXOs and settle them to your Arkade wallet.

// Settle all boarding UTXOs to your own address
const commitmentTxid = await new Ramps(wallet).onboard()

console.log('Commitment transaction ID:', commitmentTxid)

​

4. Operator includes the UTXO in a Commitment Transaction

The Arkade Operator processes the registration and includes the UTXO in a Commitment Transaction.

​

5. Receive a VTXO

Once the Commitment Transaction is confirmed, you now have a VTXO (Virtual UTXO) within a Batch Output that you can spend offchain.

While any UTXO can be used as an input, a boarding address is the preferred way as it removes the risk of a malicious user double-spending the UTXO and replacing or failing the commitment transaction.

​

Exiting

Exiting is the process of swapping a VTXO (offchain) for a UTXO (onchain). The collaborative exit process is the most efficient way to exit Arkade when the Operator is available.

​

1. Specify destination and amount

Specify the destination address and amount for the onchain UTXO.

// Specify destination address and amount
const destinationAddress = "bc1q..." // Your on-chain Bitcoin address
const amount = 50000 // Amount in sats, optional, undefined means exit all

​

2. Request settlement

Request the Arkade Operator to settle your VTXO to an onchain UTXO.

// Settle to an on-chain address
const commitmentTxid = await new Ramps(wallet).offboard(destinationAddress, amount)

console.log('Commitment transaction ID:', commitmentTxid)

​

3. Operator processes and broadcasts

The Operator includes this request in a new Commitment Transaction and broadcasts it to the Bitcoin network.

​

4. Receive onchain funds

Once confirmed, your funds are available as a standard onchain Bitcoin UTXO.

This method offers immediate withdrawal with lower delay and is operationally simpler than unilateral exits.

​

Unilateral Exit

Unilateral exit is the process of exiting a VTXO to an onchain address without the Operator’s involvement. This is a more complex and expensive process and should only be done if the Operator is not available.

​

1. Create an onchain wallet and fund it

Unilateral exit requires unrolling a set of transactions leading to your VTXO. Each transaction contains a P2A output letting to pay for the miner fees. So you need onchain funds to pay for them.

// Create an onchain wallet to pay for P2A outputs in VTXO branches
const onchainWallet = new OnchainWallet(wallet.identity, 'regtest');

// send funds to the onchain wallet address
console.log("Address:", onchainWallet.address)

​

2. Unroll your VTXO

Unrolling a VTXO is the process of putting a list of virtual transactions in a block. The current mempool limitation makes it impossible to unroll all transactions at once. So the process is sequential, where each step requires the previous transaction to be confirmed.

// unroll a specific VTXO
const outpoint = { txid: 'your_vtxo_txid', vout: 0 };
const session = await Unroll.Session.create(
  outpoint,
  onchainWallet, // the onchain wallet paying for miner fees
  onchainWallet.provider, // the onchain explorer
  wallet.indexerProvider // the ark indexer to fetch virtual transactions
);

// iterates through each step will execute them one by one
for await (const step of session) {
  switch (step.type) {
    // WAIT means we waited for the previous transaction to be confirmed
    case Unroll.StepType.WAIT:
      console.log(`Waiting for transaction ${step.txid} to be confirmed`);
      break;
    // UNROLL means we put a transaction onchain
    case Unroll.StepType.UNROLL:
      console.log(`Broadcasting transaction ${step.tx.id}`);
      break;
    // DONE means we unrolled all transactions, the VTXO outpoint is not virtual anymore
    // the loop end after this step
    case Unroll.StepType.DONE:
      console.log(`Unrolling complete for VTXO ${step.vtxoTxid}`);
      break;
  }
}

​

3. Wait for CSV locktime to be reached

VTXO unilateral exit tapscript is always locked by a relative locktime (CHECKSEQUENCEVERIFY) before being spendable.

// Try to spend the VTXO exit script
// completeUnroll fails if the locktime is not reached
await Unroll.completeUnroll(
  wallet, // the ark wallet owning the VTXO
  [vtxo.txid], // the list of VTXO transaction IDs to complete
  onchainWallet.address // the destination address (onchain) to receive the exit amount
);