The intended audience for this document is developers who need to build transactions that interact with QRC20 tokens. This document consists of two parts. The first part describes how to execute QRC20 methods and watching for events by using various RPC calls on a fully online qtumd node. The second part describes how to create QRC20 transactions without using qtumd but rather using an example Bitcoin library to achieve the same functionality. The document assumes the reader is familiar with raw Bitcoin transactions as well as the ERC20 standard and the ABI of Ethereum.
Qtum’s QRC20 standard
Qtum’s QRC20 standard is virtually identical to Ethereum’s ERC20 standard. A QRC20 token contract in Qtum typically would use the same template solidity contract as an ERC20 token. The only major exception being that Qtum’s QRC20 tokens typically use 8 decimal points instead of 18 in Ethereum.
Calldata for QRC20 calls
Calldata in OP_CALL scripts must be encoded according to the rules of the Ethereum ABI, e.g. the calldata is typically prefixed by the 4-byte function identifier. Since the word size is 256 bits, each value should be padded to 32 bytes.
Example of transfer calldata
If we want to transfer 1.1 tokens from an address we control to the address “qL1ah15xwmxLL75TBxfwiXpoovn6dKV72h”, we first set the 4 byte prefix calldata to the transfer(address,uint256) function (“a9059cbb”). Next, we translate the receiver address to its 20-byte representation in hex: “1ae4b1d517dc7d62cec8739aa3a5a8fa10c9260d” (this can be done by using the gethexaddress RPC. After this, we should encode the number of tokens we wish to transfer. This value should be multiplied by the number of decimals of the QRC20 contract. Assuming that the contract we want to call uses 8 decimals, we would therefore encode this value as 68e7780 (1.1*10^8). Next, we left pad the receiver and amount with zeroes to 32 bytes and concatenate the arguments. We would therefore have the calldata: “a9059cbb 0000000000000000000000001ae4b1d517dc7d62cec8739aa3a5a8fa10c9260d 00000000000000000000000000000000000000000000000000000000068e7780”.
Qtumd RPC
Qtumd uses the same style of RPC interface as bitcoind. Most of the RPCs available to bitcoind are available in qtumd, as well as a few Qtum specific ones. Below follows a description of a few RPCs that are useful when creating or watching QRC20 token transactions.
waitforlogs - Used for listening for new events, e.g., in the context of QRC20 tokens it can be used to listen for new Transfer() events.
createrawtransaction - Same functionality as the bitcoind equivalent with the addition of supporting OP_CALL transactions.
gettransactionreceipt - Used to get a transaction receipt that provides information of any events emitted and the execution state of a transaction (e.g., gas used and whether an exception was triggered).
callcontract - Used to perform a read-only execution of a contract. Can be used to, for example, execute balanceOf() or decimals() methods of a QRC20 contract.
sendtocontract - Used to create and sign a contract transaction that is broadcast to the network. Can for example be used to execute the transfer() or approve() methods of a QRC20 contract.
gethexaddress/fromhexaddress - Used convert Qtum’s bitcoin-style base58 addresses to and from their 20-byte representation in hex.
Examples of QRC20 contract execution
Below follows several examples executing the various functions of a QRC20 contract. These examples are run against a qtumd node running in regtest mode. You can run these examples against a testnet or mainnet node by changing the -regtest argument to -testnet or -mainnet. These examples depend on jq, python3, qtumd, and qtum-cli being installed on the target system.
Setting up a regtest qtumd node and deploying a test QRC20 contract.
To run these examples, we set up a regtest qtumd node, generate some blocks and deploy a QRC20 contract below.
To check the current token balance of an address for a QRC20 contract we need to execute the balanceOf method of the QRC20 contract. This execution should be performed as a read-only operation, which means we should use the callcontract RPC. An example is displayed below of how to check the balance of a particular address. The output is in hex, padded to 32 bytes, and should be divided by the number of decimals used in the contract.
Checking the constants of a QRC20 contract (decimals, name, standard, totalSupply, symbol)
To fetch the constants for a QRC20 contract, we need to execute the various methods of the QRC20 contract. These executions should be performed as read-only operations, which means we should use the callcontract RPC. An example is displayed below of how to check the various constants of a QRC20 contract.
The example below will watch for new Transfer events emitted by a QRC20 contract indefinitely. The example does this by continuously calling the waitforlogs RPC. The waitforlogs RPC will block until new events matching the call’s arguments are seen. When it has seen events emitted by the contract it returns a list of entries that we can iterate through to fetch the details of one or more events that were emitted. In the example below we watch for all transfer events emitted by a contract. Note: the qtumd node this runs against must be started with the -logevents argument.
# This would be run against a live node listening for new contract events forever
# Note that qtumd should be started with -logevents to enable event logging
MIN_CONFIRMATIONS=20
LAST_BLOCK=$(qtum-cli -regtest getblockcount)
TOPIC="ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
while true
do
RESULTS=$(qtum-cli -regtest waitforlogs $LAST_BLOCK null "{\"addresses\": [\"$QRC20_CONTRACT\"], \"topics\": [\"$TOPIC\"]}" $MIN_CONFIRMATIONS)
# Extract the events from the $RESULTS from .entries[topics]
for ENTRY in $(echo $RESULTS | jq -c ".entries[]")
do
TXID=$(echo $ENTRY | jq -r ".transactionHash")
SENDER_HEX=$(echo $ENTRY | jq -r ".topics[1]")
RECEIVER_HEX=$(echo $ENTRY | jq -r ".topics[2]")
AMOUNT_HEX=$(echo $ENTRY | jq -r ".data")
SENDER_ADDRESS=$(qtum-cli -regtest fromhexaddress ${SENDER_HEX:24:40})
RECEIVER_ADDRESS=$(qtum-cli -regtest fromhexaddress ${RECEIVER_HEX:24:40})
AMOUNT_TRANSFERRED=$(python3 -c "print(0x$AMOUNT_HEX)")
echo "TXID: $TXID"
echo "SENDER: $SENDER_ADDRESS"
echo "RECEIVER: $RECEIVER_ADDRESS"
echo "AMOUNT: $AMOUNT_TRANSFERRED"
echo ""
done
LAST_BLOCK=$(echo $RESULTS | jq -r ".nextblock")
done
Example of QRC20 transfer using an online qtumd node for signing
The easiest way to do a transfer between different addresses for a QRC20 contract is to simply use the sendtocontract RPC.
QRC20_SENDER="qauZFnmbNBNuY2ujQateDwzvL6zoxBiY3H"
QRC20_RECEIVER="qL1ah15xwmxLL75TBxfwiXpoovn6dKV72h"
QRC20_TOKEN_TRANSFER_VALUE=1.1
QRC20_DECIMALS=8
# Adjust the tokens to transfer by the decimals and store the result in hex padded to 32 bytes
QRC20_TOKEN_TRANSFER_VALUE_PADDED_HEX=$(python3 -c "print(hex(int(${QRC20_TOKEN_TRANSFER_VALUE} * 10**0x${QRC20_DECIMALS}))[2:].zfill(64))")
# Convert the base58 receiver address into its 20-byte hex-encoded equivalents
QRC20_RECEIVER_HEX=$(qtum-cli -regtest gethexaddress $QRC20_RECEIVER)
# Pad the receiver hex to 32 bytes
QRC20_RECEIVER_PADDED_HEX="000000000000000000000000${QRC20_RECEIVER_HEX}"
# The function hash of "transfer(address,uint256)" concatenated with the receiver address and number of tokens to transfer
CALLDATA="a9059cbb${QRC20_RECEIVER_PADDED_HEX}${QRC20_TOKEN_TRANSFER_VALUE_PADDED_HEX}"
# Create, sign and broadcast the transfer
qtum-cli -regtest sendtocontract $QRC20_CONTRACT $CALLDATA 0 100000 0.0000004 $QRC20_SENDER
In depth on Qtum transactions
Qtum uses Bitcoin-style transactions. The transaction format is basically identical to Bitcoin transactions with a few modifications to the Bitcoin scripting engine. Qtum introduces 4 new opcodes in the scripting engine to allow for interaction with the Qtum EVM. The only relevant opcode for this document is OP_CALL (0xc2).
OP_CALL
The OP_CALL opcode allows transaction output scriptPubKeys to be used to execute smart contracts in the Qtum EVM. The format for an OP_CALL scripts is the following:
version gaslimit gasprice calldata contractaddress OP_CALL
field name
size in bytes
typical value
description
version
1
0x04
The version of the script, will always be 0x04 for purposes of this document.
gaslimit
variable
200000
The gas limit of the EVM execution, should be the same as the same limit in Ethereum for the purposes of this document.
gasprice
variable
40
The price per unit of gas, should typically be set to 40 as that is the current minimum limit for the gas price. Identical to the same concept in Ethereum.
calldata
variable
-
The ABI encoded calldata, the same as in Ethereum, i.e., typically a 4-byte function signature followed by the ABI encoded function arguments. Identical to the same concept in Ethereum.
contractaddress
20
-
The address of the contract you wish to execute.
OP_CALL
opcode
0xc2
The OP_CALL opcode.
The script must follow the same rules for encoding as a typical bitcoin script, e.g., each value that is not an opcode will be prefixed with a push length unless it is a “smallint” (typically any bitcoin library used for creating a transaction will handle these details). Below is a transaction that contains an output that uses an OP_CALL scriptPubKey to execute a contract in Qtum.
Transaction Signing
The process of signing a raw transaction in Qtum is identical to signing a Bitcoin transaction. Typically, a raw transaction is signed using the signrawtransactionwithkey or signrawtransactionwithwallet in qtumd. Also, any Bitcoin library should be possible to be used to sign raw Qtum transactions.
Example of a raw QRC20 transfer using a Bitcoin library
Described below is the process of creating and signing a raw QRC20 transfer transaction using the bitcoin-js library.
var bitcoin = require('bitcoinjs-lib');
var testnet = bitcoin.networks.testnet;
/*
Example of transaction that creates and signs a QRC20 transfer transaction for Qtum using the bitcoin-js library.
The transaction format is nearly identical to that of Bitcoin, except for the OP_CALL output.
Note, since OP_CALL is a Qtum specific opcode, it needs to be hardcoded as 0xc2
The script below will assume that the input tx being spent is a P2PKH output.
*/
// The input tx hash and vout of the utxo we are going to spend
const TXINHASH = "e06d87ecfc8563e899118de9b9fc9deafc9aba41f2c420075bbf2c610fe160fc";
const TXINVOUT = 0;
// The WIF key of the input key. Qtum uses the same WIF format and prefx as Bitcoin
const TXINKEY = bitcoin.ECPair.fromWIF('cVNrcCHX5q318dDkpMFoLD1ack7TybxEjFB44xCsv5sW35kM7QuE', testnet);
// The value of the utxo, Qtum uses the same number of decimals as Bitcoin (8 decimals)
const TXINVALUE = 2000000000000;
// The contract address we wish to call
const QRC20_CONTRACT = "a20ee8612b8d338c55dcd03e65544339efd7cebc";
// The receiver address. Note that the SENDER is the address of the UTXO we are spending.
const QRC20_RECEIVER="qauZFnmbNBNuY2ujQateDwzvL6zoxBiY3H";
// The number of tokens we want to transfer
const QRC20_TOKEN_TRANSFER_VALUE=1n;
// The number of decimals defined by the QRC20 contract.
const QRC20_DECIMALS=8n;
// The minimum gas price is 0.00000040 Qtum, so we set the gas price to that here
const GASPRICE = 40;
// The gas schedule of Qtum is virtually identical to that of Ethereum, so a value that works for Ethereum will typically work for Qtum
const GASLIMIT = 100000;
// The OP_CALL (0xc2) opcode is Qtum specific and must therefore be hardcoded.
const OP_CALL = 0xc2;
var qrc20_receiver_hex=bitcoin.address.fromBase58Check(QRC20_RECEIVER)['hash'].toString('hex')
var qrc20_token_transfer_value_adjusted=QRC20_TOKEN_TRANSFER_VALUE * (10n**QRC20_DECIMALS);
var qrc20_token_transfer_value_adjusted_hex=("0".repeat(64) + qrc20_token_transfer_value_adjusted.toString(16)).slice(-64)
// The calldata, should be ABI encoded according the Ethereum ABI specification.
var calldata = "a9059cbb000000000000000000000000"+qrc20_receiver_hex+qrc20_token_transfer_value_adjusted_hex;
// The input value minus the gas cost/txfee
var changeValue = TXINVALUE-(GASPRICE*GASLIMIT);
// The opcall scriptPubKey on the form of "version gaslimit gasprice calldata contractaddress OP_CALL"
var contractCallScript = bitcoin.script.compile([
bitcoin.script.number.encode(4), // version
bitcoin.script.number.encode(GASLIMIT), // gas limit
bitcoin.script.number.encode(GASPRICE), // gas price
new Buffer(calldata, "hex"), // The ABI encoded calldata
new Buffer(QRC20_CONTRACT, "hex"), // the contract's address
OP_CALL // OP_CALL opcode
]);
// A normal P2PKH change output
var changeScript = bitcoin.script.compile([
bitcoin.opcodes.OP_DUP,
bitcoin.opcodes.OP_HASH160,
new Buffer(bitcoin.crypto.hash160(TXINKEY.publicKey)),
bitcoin.opcodes.OP_EQUALVERIFY,
bitcoin.opcodes.OP_CHECKSIG
]);
var txb = new bitcoin.TransactionBuilder(testnet);
txb.addInput(TXINHASH, TXINVOUT);
txb.addOutput(contractCallScript, 0);
txb.addOutput(changeScript, changeValue);
txb.sign(0, TXINKEY);
var tx = txb.build();
console.log(tx.toHex());
Notes
The first input to the transaction must be the sender (unless you use OP_SENDER style scripts, which is not covered in this document)
If you use
Any Bitcoin library should be possible to use for signing, as long as it is possible to manually encode the OP_CALL opcode in the script.