Getting Started with the Alpha Sidechain
You might have heard of Sidechains by now – a way to test new blockchain ideas, while still being protected the security of the Bitcoin mining network. Blockstream has been hard at work turning this idea into a reality, and recently they released the Elements Project, which puts a huge list of powerful new tools into the hands of developers. One of those tools is [alpha, a sidechain pegged to Bitcoin’s testnet][alpha], which implements a majority of the Elements to date.
So what’s the first thing we’re going to do? Start playing with it, of course.
You’re going to need to grab a few dependencies before you can compile. If you’ve already compiled Bitcoin before (a process I recommend everyone go through), you probably have most of the required components – you can skip ahead to compiling Elements itself. For others, I’m going to start with one of the most common developer setups, a modern Linux distribution (Ubuntu in our case) and compiling everything from scratch.
Let’s go ahead and get our basics complete. For now, that starts with getting
a compiler and all the build tools. In Ubuntu, this is provided by the
We’re also going to want a few extra tools, perhaps most notably
Bitcoin and Elements also require a list of dependencies you’ll need installed
before you’re able to compile, including
libboost, and a number of
Important! Make sure to use
libdb5.1 or later! 5.1 will break certain functionality in Bitcoin and will not be conducive to a
successful build! An installation candidate for 4.8 can be made available by adding the Bitcoin PPA to your apt sources (see below).
libboost-all-dev is available on Ubuntu, but might not be so
convenient on other distributions. Your mileage may vary – try compiling and
simply installing the packages the compiler claims are missing.
We’re ready to download and compile the main body of work that comprises Elements. Like any other compiled package, we’ll first acquire the source code, then configure it for our environment, and finally compile it into some executable binaries.
Note: personally, I prefer keeping everything in a distinct project folder.
To do this, I execute this first:
mkdir sidechains && cd sidechains – you’ll
likely be better organized in the long run if you start this way!
Download the code via Git:
If you’d like, you can even fork the above repository on GitHub, and replace the git URL with your personal one. This is generally my approach.
You’re now in the
elements directory. Let’s compile
bitcoin itself, which
is a necessary component for any sidechain:
Give it a little while to configure and compile – this can take a significant
amount of time, depending on the speed of your computer. Once complete (so long
as there are no errors), you should be able to execute
ls .. and see three
bitcoin-tx. You’re ready to move
Let’s checkout the
alpha branch, which contains Blockstream’s proposed
improvements to Bitcoin to implement sidechains, and complete the same process:
Again, provided there are no errors,
ls .. should now include three additional
alpha-tx – these are the
Elements-specific binaries that implement sidechains, and expect to be able to
connect directly to the
bitcoind instance you compiled earlier.
Let’s fire these babies up.
Now that we have working binaries for both Bitcoin and Elements, we can start
running them as nodes. We’ll be joining them to
testnet3, the latest testnet
on the Bitcoin network.
You’ll have to run two different binaries at once here - I’ll leave that as an
exercise to the reader to manage, if I only insist that
tmux provides a
wonderful split-screen capability within a single terminal!
Firstly, it’ll help to alias some variables to configure the authentication for the RPC communication between the Elements and Bitcoin binaries:
In screen one, let’s get our Bitcoin daemon started:
Since this will be the first time we’ve started our Bitcoin client, it will take
some time to synchronize (generally 2-3 hours). Let’s go ahead and fire up the
Elements binary before we go grab some coffee, though – again, very similar to
before, but this time with the
You’ll notice some additional parameters, including
-blindtrust, but also some RPC parameters specifying where it can find a
“trustworthy” Bitcoin node. In this case, we’re supplying our own node, which we
have compiled ourselves and know to be valid.
When both clients complete their synchronization, you’re now a fully functional Elements/Bitcoin pair on the
testnet3 network! Now’s your chance to go grab
a coffee while we wait for that to complete.
Hopefully you’ve given both Elements and Bitcoin enough time to sync by now.
The next natural step is to try moving some money into the network – to do this,
we’ll need some
testnet3 Bitcoin to spend into the sidechain to acquire our
sidechain’s tokens, and then we can spend those sidechain tokens to re-acquire
As this is intended as a developer preview, we don’t have fancy interfaces for moving money around – we’ll need to build a few for ourselves.
Up first is the
secp256k1 library, which exposes all of the standard k1 curve
The only notable component here is that we’re using
make install with a target
directory – we’ll use this now for static linking in
One last tool and we’re almost ready – let’s get a copy of Jeff Garzik’s RPC
Now, we’re ready to move money.
Let’s generate a new sidechain wallet to store the tokens we’re about to create
when we commit our testnet Bitcoin. Go ahead and run
cd elements to get into
the appropriate folder.
Since we just installed Bitcoin for the first time above, we probably don’t have
testnet3 bitcoin. Blockstream has their own testnet faucet for this purpose; let’s get our Bitcoin address and request some funds:
You’ll get an output of an address – make sure it starts with an
m or an
designates a testnet address–and plug that into the
testnet3 bitcoin faucet
to request some coins.
Note: If you set a custom RPCUSER and RPCPASS in the earlier step, you’ll
need to edit
./contrib/sidechain-manipulation.py now to reflect those values somewhere
around lines 9 and 10.
You’ll see something like this as an output:
Let’s copy that P2SH address and use it to send some money:
Don’t forget to replace the address with the one you generated above, and to
supply the amount you’re sending. You should see an output something like this:
Take note of both the
nonce and the transaction ID. We’ll need them to stake
our claim to the corresponding sidechain tokens in a moment.
Now, due to the nature of this sidechain implementation, you’ll need to wait 10
blocks on the testnet blockchain for this transaction to be redeemable in the
sidechain. This amounts to around 1.5 hours on
mainnet, but shouldn’t take
nearly this long on
Once completed, let’s go ahead and claim – don’t forget to replace the
and transaction ID values, in that order:
Again, the output will look something like this:
You’ve now got a spendable transaction on your sidechain! Well, it’ll be redeemable in 144 sidechain blocks to make sure any outstanding forks are resolved, but we’ve just claimed our first tokens in the sidechain.
We can now spend it using our 1-of-1 address from earlier:
In this initial release of Elements, we’ve implemented something called
“federated peg”. Since the main Bitcoin codebase does not yet support some of
the necessary features to implement a full two-way peg, the
relies on a group of signatories (the “federation” part) to execute and verify
the redemption of testnet coins, while within Elements the network actually
utilizes a full two-way peg to redeem the outputs from testnet.
Let’s take a look at what happens now.
To complete the loop, we need to get rid of our sidechain tokens, and restore the original bitcoin we spent in creating them. In our federated peg, we rely on the federation to verify these, but once bitcoin supports the types of smart contracts we need, it’ll be completely two-way in both directions.
Generate yourself a mainchain wallet to receive the restored bitcoin:
Finally, provide the P2SH address you just created above to the
send-to-mainchain command, and the amount you wish to move (this can be any
subset of the amount you moved in earlier, but no more):
That’s it! We’ve spun up both a Bitcoin node on the
testnet3 network, and an
Elements node on the
alpha network. We’ve moved
testnet3 bitcoin into the
alpha sidechain, moved it around, and finally returned ourselves to
There’s a ton of other things that Elements provides, including Segregated Witness and Confidential Transactions. Now that you have an Elements node running, you can explore these things and more on your own. We’ll cover these in more detail in the future!
Until then, please share what you build and help us by reporting any issues you find on the official Elements GitHub repo. We’re excited to see what you build!