Elements code tutorial
Setting up your working environment
First we need to set up our working directories. Start by moving to the home directory:
cd
We’ll create some test directories to hold the data used by our Bitcoin node and also two instances of an Elements node. First we’ll try and remove any files and directories that might be left over from running through this tutorial previously. Don’t worry if the first 3 lines throw errors, it just means the directories are not there and can’t be removed.
rm -r ~/bitcoindir
rm -r ~/elementsdir1
rm -r ~/elementsdir2
mkdir ~/bitcoindir
mkdir ~/elementsdir1
mkdir ~/elementsdir2
We need to set up our config files now. We’ll do that by writing some settings to the working directories we just created.
The Bitcoin config file:
echo -n "regtest=1
txindex=1
daemon=1
rpcuser=user3
rpcpassword=password3
fallbackfee=0.0002
[regtest]
rpcport=18888
port=18889
" > ~/bitcoindir/bitcoin.conf
Elements 1 config file:
echo -n "chain=elementsregtest
rpcuser=user1
rpcpassword=password1
daemon=1
server=1
listen=1
txindex=1
validatepegin=1
mainchainrpcport=18888
mainchainrpcuser=user3
mainchainrpcpassword=password3
initialfreecoins=2100000000000000
fallbackfee=0.0002
[elementsregtest]
rpcport=18884
port=18886
anyonecanspendaremine=1
connect=localhost:18887
" > ~/elementsdir1/elements.conf
Elements 2 config file:
echo -n "chain=elementsregtest
rpcuser=user2
rpcpassword=password2
daemon=1
server=1
listen=1
txindex=1
mainchainrpcport=18888
mainchainrpcuser=user3
mainchainrpcpassword=password3
initialfreecoins=2100000000000000
fallbackfee=0.0002
[elementsregtest]
rpcport=18885
port=18887
anyonecanspendaremine=1
connect=localhost:18886
" > ~/elementsdir2/elements.conf
If you take a quick look in each of the 3 config files you will see that they contain a flag to tell the nodes to operate in “regtest” mode. They also contain RPC information such as port, username and password. The Elements config files also contain details of the Bitcoin node’s RPC authentication data. They need access to this information in order to authenticate and make calls to the Bitcoin node later.
By using a different port for each Element daemon we can run more than one node at a time on a single machine. This is useful for the purposes of our tutorial.
Before we start running our nodes we’ll take the time to configure some terminal aliases. These will let us pass commands to each node’s client in a much simpler way.
Before we do that it is worth noting how the set up of a daemon and client works for both Bitcoin and Elements.
The Bitcoin and Elements node software (bitcoind, elementsd) both run as daemons, executing code as background services that can be remotely accessed using the Bitcoin and Elements client software (bitcoin-cli, elements-cli). The clients simplify the process of sending commands to their associated daemon and receiving the returned output data.
Note: Once our Bitcoin and Elements daemons have been started we will only interact with them through the use of the clients, which will use the same config file as their associated daemon, enabling them to pass authentication checks when making RPC calls.
Now let’s create the terminal aliases for our Bitcoin and Elements daemons, clients and the Elements QT front end:
cd elements
cd src
shopt -s expand_aliases
alias b-dae="bitcoind -datadir=$HOME/bitcoindir"
alias b-cli="bitcoin-cli -datadir=$HOME/bitcoindir"
alias e1-dae="elementsd -datadir=$HOME/elementsdir1"
alias e1-cli="elements-cli -datadir=$HOME/elementsdir1"
alias e2-dae="elementsd -datadir=$HOME/elementsdir2"
alias e2-cli="elements-cli -datadir=$HOME/elementsdir2"
alias e1-qt="elements-qt -datadir=$HOME/elementsdir1"
alias e2-qt="elements-qt -datadir=$HOME/elementsdir2"
You’ll need to ensure that the directories containing bitcoind, bitcoin-cli, elements-cli, elementsd, and elements-qt are in the PATH environment variable.
We now have an easy way to start each daemon and the Elements QT front end and make simple calls to the clients. Instead of having to type “elements-cli -datadir=$HOME/elementsdir1” every time we want to make a call to the Elements client, we can just use the “e1-cli” alias for example.
Note: If you want to skip ahead to running a non-sidechain Elements based blockchain you can move to the Elements as a standalone Blockchain section now. You can return to the Using Elements to perform basic operations section after that, but you may have to amend the commands used occasionally.
If you want to run a few examples of your own after following this tutorial you can add the aliases above to your ‘bashrc’ file which means that they will be available to you in every new terminal window you open. To do this run “nano ~/.bashrc” and paste the 8 alias lines above into the file, save and exit. The next time you open a new terminal window the aliases will have already been set.
Note: We won’t be using the Elements QT front end in this tutorial but you can start it using the alias we created above (e.g. e1-qt) if you want at any point to see a GUI for your wallet. Note that you cannot run the daemon and QT at the same time as they will both be trying to access the same data directory.
We don’t need to do this now but if at any point you need to exit the tutorial and start again you should run the following commands to shut down the Bitcoin and Elements daemons first before restarting:
b-cli stop
e1-cli stop
e2-cli stop
If we now try and execute a simple command using the Bitcoin RPC client it will error as we haven’t started the Bitcoin daemon yet:
b-cli getblockcount
That gives us an error, but we were expecting that. Let’s start the Bitcoin daemon:
b-dae
Give it a few seconds to start up, and then try again:
b-cli getblockcount
That should work! It doesn’t matter what the number returned is, and it may well be zero, as long as you get a response.
Now let’s create a default wallet:
b-cli createwallet ""
Note: If you are running Bitcoin Core version 0.21.0 or newer, you will have to create a new wallet like we have done. For previous releases, a new wallet is automatically created on startup.
We can check the balance using:
b-cli getwalletinfo
So now we have the Bitcoin daemon running we need to start our Elements daemons. Remember that we are able to run two instances on the same machine because we are using different configuration files with different ports and RPC permissions set. Start the daemons:
e1-dae
e2-dae
Give them a few seconds to start up and then create the default wallets for each node. We also call rescanblockchain so the nodes are aware the new wallets can access the initial free coins set within the config files.
e1-cli createwallet ""
e2-cli createwallet ""
e1-cli rescanblockchain
e2-cli rescanblockchain
Then check the balances using:
e1-cli getwalletinfo
e2-cli getwalletinfo
A quick query of the running processes should also list them as active:
ps -A | grep elementsd
The two instances should show in the list.