Sidechains: Alpha Sidechain Tutorial

In this tutorial we will take a practical look at sidechains [1]. We will concentrate on the Elements project [2] and its first sidechain known as Alpha . Alpha is a developer sidechain that is pegged to Bitcoin’s testnet [3]. In order to play around with sidechains in general and with Alpha in particular we need to have the mainchain installed on our machine. The mainchain in our case is the bitcoin testnet. Then we will need to install the Alpha sidechain. Let’s proceed. The instructions below are for Linux Ubuntu.

Step 1 – Install bitcoind & alphad

  • First we need to get some dependencies:

  • If you do not have git installed on your machine:

  • To be organized let’s create a sidechains directory:

  • Now let’s go ahead and clone the Elements Project:

  • let’s install the mainchain:

  • move the newly built binaries out of the src folder:

  • let’s install the alpha sidechain:

  • move the newly build binaries out of the src folder:

    Step 2 – Run and Synch bitcoin testnet

  • First let’s set some values for the RPC user and password so we do not need to retype them each time:

  • Now let’s run bitcoind in testnet mode

  • While the testnet is synching, we can start alphad. I would recommend opening a new terminal window. We have to set the RPC values in this terminal instance as well. Then navigate to the elements directory, and then run alphad:

  • You can now take a break and give both chains time to download their blockchains

    Step 3 – Make sure bitcoind and alphad are running

  • bitcoin-cli -testnet -rpcuser=$RPC_USER -rpcpassword=$RPC_PASS getblockcount
  • alpha-cli -testnet -rpcuser=$RPC_USER -rpcpassword=$RPC_PASS getblockcount
  • both commands should produce a numeric output. At the time of this writing Bitcoin testnet is in the 720,000’s block [4], and the alpha testnet is in the 130,000’s block [5].

    Step 4 – Get some bitcoin testnet coins

  • bitcoin-cli -testnet -rpcuser=$RPC_USER -rpcpassword=$RPC_PASS getnewaddress
  • Once you have your testnet address you can go visit any of the testnet faucets to receive some coins. For example try
  • check your balance (remember it takes a few blocks before you see the transfer)
    bitcoin-cli -testnet -rpcuser=$RPC_USER -rpcpassword=$RPC_PASS getblalance

    Step 5 – Install the necessary tools to transfer funds between chains

  • first we will need the secp256k1 library, put it in the sidechains folder:

  • next up is contracthashtool:

  • Now we will need Jeff Garzik’s python RPC library:

    Step 6 – Modify sidechains/elements/contrib/ to include your credentials

  • In our case the lines in question are #53 and 54. Originally they look like the following:

  • We want to change user to our own RPC_USER set before and pass to our own RPC_PASS
    In our case it would be:

  • don’t forget to save the file
  • Step 7 – Send coins to the alpha sidechain

  • Now, we are ready to transfer some tBTC to the Alpha sidechain
  • make sure you’re in the elements directory

  • we got the following output:

  • Now we are ready to send coins to the Alpha sidechain
    We will use the send-to-sidechain command; as arguments it takes the sidechain address and amount of coins to send

  • In our case we do the following:

    the output looks like the following:

    Step 7a – (Optional) Check the transactions

  • Switch to the terminal where you are running bitcoind and issue the following command:
    In our case:
    bitcoin-cli -testnet -rpcuser=$RPC_USER -rpcpassword=$RPC_PASS gettransaction d93beb30b86971b79b9cac9e42d5bd0ed3ad66354e9d6c006ee39fb2ae1d52b9

    Now we wait 10 bitcoin testnet blocks before we can claim the funds on the Alpha sidechain

    Step 8 – Claim the coins to the alpha sidechain

  • We will use the claim-on-sidechain command, as arguments it takes the sidechain address, the nonce, and the transaction id we got when we sent coins to the sidechain:

    In our case we do the following:
    claim-on-sidechain 2N8qM71fbG1DiWcuDCLP7negcKq3X1rmhyE 2452357eb5e1e471378ebda207e4305b d93beb30b86971b79b9cac9e42d5bd0ed3ad66354e9d6c006ee39fb2ae1d52b9
    The output looks like the following:

    Now we need to wait 144 alpha sidechain testnet blocks before we can redeem the coins

    Step 8a – (Optional) check the transaction on the alpha sidechains
    First we get the raw transaction using the tx id we got from claim-on-sidechain :

    Now we decode the raw transaction:

    We can see the values both on the mainchain and the sidechain sides.

    The Alpha Sidechain has been down since Feb 22, last block reported is 130238, so the next steps are not tested on a live network. (we need the 144 confirmations)

    Step 9 – Spend funds from the claim

  • We will use the spend-from-claim command, as arguments it takes the transaction id we got when we claimed coins to the sidechain, and our sidechain address (starting with 22)

  • In our case we do the following:
    spend-from-claim 2f7abb3d4dee1183ce7d85a488cef8e0692926879672ffd57b1db8b3dbd4d2f9 22E8UzLXiZrtSZfqqmEdjqJsk1RBqdpnPmbXYkDVHxrveGb2DVNcic9ksGGS2xiXAE2hvqGNEJp3zoijb

    Step 10 Transfer the sidechain tokens back to the mainchain

  • First we generate a mainchain wallet address
    ./contrib/ generate-one-of-one-multisig mainchain-wallet
    The output will be a one-of-one address and a P2SH address

  • Now we use the P2SH we received with the send-to-mainchain command to move the coins back. We can send back any amount, up to the original amount transferred

    That completes the loop.

    In this tutorial we examined the Elements project. We showed how to install both a mainchain node and an Alpha sidechain node. Then we acquired the necessary tools to accomplish transfers between the chains. We transferred funds from the mainchain to the sidechain. Sadly the Alpha sidechain is currently down so we could not complete the tutorial on a live network. We did however, include the steps necessary to spend the claim on the sidechains network and to transfer the coins back to the mainchain from the sidechain. We have only encountered one error which we describe in Appendix A. We hope that you find this tutorial useful. Sidechains may prove to be an important part of the blockchain ecosystem.

    Appendix A
    Error while trying to claim-on-sidechain

    Fix the error by modifying elements/src/script/interpreter.cpp
    as shown here:


  • Leave a Reply

    Your email address will not be published. Required fields are marked *