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.

Boarding addresses resemble VTXOs but typically use longer timelocks to reduce risk.

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
);