Qtum Dapp Developer — Basic usage of QTUM AMI on AWS EC2 Instance
On July 2018, AWS released QTUM Amazon Machine Image (AMI).
This image makes it possible to get started with QTUM quickly without having to worry too much over configuration.
Prerequisites:
- A running instance of QTUM AMI you can connect to with ssh. If you don’t have one and/or do not know where to start, check my previous article on the subject: Run QTUM AMI on AWS EC2 Instance
It will help you setting up, running and connecting to such an instance.
This tutorial is aimed for QTUM Dapp developers willing to use QTUM AMI.
QTUM AMI comes with Qtum Core, Qmix web IDE, and Solidity already installed. We are going to see how to interact with each of them three.
All following tutorial assume you are connected with ssh to your instance (see previous article if needed):
1 — Launch QTUM Core
First, QTUM AMI comes with qtumd installed. It is the command used to start your QTUM Core.
Start by QTUM node on your instance:
qtumd
You can use -testnet option if you want to start testnet (by default the mainnet starts)
You can use -daemon option if you want the process to run in the background so you can run commands after. If you start it like this as daemon, if you need to stop it later on, you can use command: qtum-cli stop.
Note: you can get help for qtumd with command: qtumd -h
qtumd command will start the Qtum Core. You will see a .qtum directory appearing in /home/ubuntu. This directory is the default to store the local chain info (in Linux, which is OS AWS installed). Note that you can change this location if desired, check qtumd help if you want it.
When you start the qtumd, your local chain will automatically start synchronising.
The base command to interact with your running Qtum core is:
qtum-cli
To get help, use:
qtum-cli — help (shows help for qtum-cli)
qtum-cli (shows list of commands)
qtum-cli [command] — help (shows help for a command)
You can verify your node is connected to the QTUM network with command:
qtum-cli getnetworkinfo
You should see displayed:
“networkactive”: true, “connections”: X (>0)
How to know your node has finished synchronising with network ?
I first found it hard to know when dealing with qtumd. Solution is actually pretty simple. Run command:
qtum-cli getblockchaininfo
and check value: verificationprogress. If it’s 1, then your local chain is fully synchronised.
Note: Synchronisation can take many hours to complete, and will depends on Instance Type you chose for your EC2 instance, network, nodes…just be patient :)
qtum-cli will be your go-to command to communicate with your node locally (directly on instance). With it you can for example:
- get new QTUM addresses (remember, with UTXO model a wallet has many addresses, one per transaction being ideal)
- send/receive QTUM tokens,
- send transactions
- sign transactions
- stake QTUM tokens
- protect your wallet
- …and so on.
This tutorial won’t cover further possibilities offered by qtum-cli. If you want to learn more about it, I suggest you to start by having a look to at official documentation: https://docs.qtum.site
If you want to use QTUM core directly from the instance only (with qtum-cli), you are good to go and can directly go to next part. However…
…what if you want to use your fresh node from outside ?
For example, from a client and/or server where your Dapp logic is ?
For this, you need some more setup to do for your QTUM AMI to be usable, and I found it difficult to find info for this …so here it is:
Let’s expose AWS EC2 3889 and 13889 Ports
First…. you have to know that by default your QTUM AMI does not expose any more ports than 5555 for QMIX (see next section), 22 for SSH connection (we used to connect to EC2 instance in previous tutorial), and 3888 Ports.
BUT, when you run qtumd or qtumd -testnet, ports used by default are 3889 and 13889. (3889 for mainnet, and 13889 for testnet)
So, follow theses steps to open these ports on AWS EC2:
1/ Go back to SERVICES > EC2: https://console.aws.amazon.com/ec2/
2/ Click on Running Instances
3/ Add the end of the line of your QTUM Instance, in Security Group Column, you will see some link looking: Qtum AMI-Qtum AMI 1–0-AutogenByAWSMP-2. Click on it
4/ At the bottom of the page, click on Inbound tab.
5/ Click on Edit
6/ A modal opens, click on Add Rule
7/ For the new Rule, select Custom TCP Rule, Port Range 3889, source 0.0.0.0/0. If you want to call testnet network too from outside your instance, do the same for port 13889. Of course, if you changed default ports for qtumd at starting time, use them (though if you followed the tutorial, just used default ports).
8/ Click on Save.
9/ Congrats, your AWS EC2 instance now accept connections to 3889 and 13889 ports.
Now, let’s restart qtumd to define authorised user / ip to call your node from outside
1/ If qtumd is running, stop it with qtum-cli stop
2/ Start it again with command:
qtumd -rpcuser=clement -rpcpassword=test -rpcallowip=XX.XXX.XX.XXX/255.255.255.0
Note that: clement should be replaced by the username you want, test by the password your want and XX.. by your IP (or IP of client calling it). username and password you set will be needed later to call your running Qtum core.
Note that you can use -rpcallowip option multiple times if you need to authorise many IPs.
3/ Time to test! From previously authorised IP, try following command:
curl — user clement:test — data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getwalletinfo”, “params”: [] }’ -H ‘content-type: text/plain;’ http://XXX.XXX.XXX.XXX:3889/
Don’t forget replacing clement:test by your username:password you just set, and XXX.XXX.XXX.XXX by your AWS EC2 instance IPV4 (not your authorised IP :).
…And you should get results ! Congrats!
Now, you have a Qtum node running and can communicate with it from the outside, with user/password you defined and from an IP you authorised.
You can now use it in your project to speak with QTUM blockchain.
For example, using QtumJS from Qtum, you can do:
const rpc = new QtumRPC('http://clement:test@XXX.XXX.XXX.XXX:3889');
const info = await rpc.rawCall("getwalletinfo");
2— Use QMIX
QMIX is the QTUM equivalent of Ethereum Remix project.
It allows you to write, debug, compile, and deploy smart contract on QTUM blockchain. Not bad eh?
And actually…it’s already running and available on port 5555 on your EC2 instance.
If your Ipv4 address for your running AWS EC2 instance is:
111.222.333.444
(Note that you can find it on your AWS EC2 Dashboard at: https://console.aws.amazon.com/ec2/)
Then QMIX is available for you at URL:
http://111.222.333.444:5555
I won’t go deeper into QMIX in this tutorial.
However, if QMIX interests you (and it should), you can check this article for QTUM Dapp developpers beginners:
There is a video inside with a very nice QMIX Demo.
3/ Solidity
Inside the AMI, the Solidity compiler is available too. You can access it with command:
solc ( — help if you want to know about how to use it)
Many tutorials are available online on solc usage so I won’t cover it here neither.
That’s all! You should now have a better understanding on how to get started with QTUM thanks to QTUM AMI on AWS.
Hope you enjoyed & Happy coding!
Some link to go further:
- QMIX
- Solc documentation
- QtumRPC methods (you can access them all with command: qtum-cli [method])
- Official Qtum doc
- In particular, qtumd / qtum-cli doc (some of which was used to write this tutorial):
If you have any idea(s)/suggestion(s), have spotted error(s), and/or would like me to detail more some part(s), do not hesitate commenting this article so I can improve this tutorial.
You like what you read? Help me dedicate more time writing on QTUM.
QTUM address: QYc3fTQYVZtYUCrrVRVFv4QKHk5gQ4WKie
