Smart Chain API Basics
API Tutorials: Introduction
The following tutorial can assist in gaining hands-on experience with the essential Smart Chain API.
In this tutorial, we create two new blockchains, called RT1 & RT2.
The first blockchain, RT1, demonstrates the fundamental API concepts, such as how to create and utilize a simple test blockchain, how to query a blockchain for data, etc.
<!--
Sidd: Mylo, your original sentence cut off here!
The RT2 blockchain demonstrates the creation of a custom application-specific blockchain that
-->
For simplicity's sake, we use the blockchain regtest feature, which allows us to run a blockchain on a single node without having to connect to a network.
After the tutorial, the developer should be able to repeat the same concepts on live and fully functional Indexchain Smart Chains, assuming the Smart Chain in question has the proper CC features enabled.
Tutorial Topics Outline
Topics covered in this tutorial include:
How to create a simple Smart Chain for testing purposes
How to execute a komodo-cli command to query the blockchain for existing data
How to execute a curl command for the same purpose
Understanding common API methods ("RPC's")
Understanding common technology concepts in the Indexchain ecosystem
Tutorial Prerequisites
komodod and komodo-cli
The following tutorials assume that you have already compiled the Komodo daemon, and that you have used the default ~/komodo/src directory as the root Komodo software directory.
As with all software related to komodod, at the command line we use the terminal-based komodo-cli software, and the curl command, to access the daemon.
Indexchain API Fundamentals Tutorial
Create a Regtest Blockchain
The quickest way to establish your own development environment is to use the regtest feature.
In regtest mode, the daemon creates a blockchain that is almost fully functional, save for a few exceptions. Two of the exceptions are that the chain runs on a single host, and the user instructs the daemon on when and how to perform new blocks (as opposed to receiving new blocks from a decentralized network of miners).
The command to create our RT1 regtest chain is as follows:
ac_supply
Note the -ac_supply=1000 argument. This is the total number of coins we desire when the blockchain spawns.
For more information, refer to the ac_supply launch parameter.
ac_name
Also note the -ac_name=RT1 argument. This is the blockchain ticker name we desire. For more information, refer to the ac_name launch parameter.
There are many additional parameters that you can explore later in the Antara Customizations documentation.
Observe the Response
The daemon will return a response similar to the following:
From the response, note the following information:
Smart Chain Supply
We see the 1000 coin initial supply.
Configuration File Location
This is the location of the configuration file.
Placing the configuration data here follows the Indexchain convention of placing all relevant data for a Smart Chain in a subdirectory contained in the ~/.komodo/ directory. The new subdirectory for our regtest chain is named after the RT1 value we gave to the ac_name parameter.
Relevant RPC Data
This information is the blockchain name, its network ports used for p2p (13100), and RPC control (13101). The magic number is a number the Indexchain daemon uses for network purposes, and the number of coins is informational.
Explanation of All Initial Daemon Output
Here is an explanation of all of the output, as it appears in the above response. Many of the actual values will be different on your machine, although the underlying purpose of the value is the same.
Value
Description
[1] 22892
the process number; the value is dependent on your machine and will be different
ASSETCHAINS_SUPPLY 1000
the number of coins when the blockchain initiates for its first time
MAX_MONEY 106320417438 1063.20417438
this value is not important at this time; it states that 100 billion coins is the maximum possible amount the blockchain can mathematically support
Created (/home/mylo/.komodo/RT1/RT1.conf)
the location of the configuration file
call komodo_args.(./komodod) NOTARY_PUBKEY.()
this value specifies where the new coins from block rewards are sent; by default, the coins will be sent to your node's local wallet
>>>>>>>>>> RT1: p2p.13100 rpc.13101 magic.fd772ab9 4252445369 1000 coins
the blockchain name, its network ports and RPC controls; the magic number is used in Indexchain networking and the number of coins derives from the ac_supply parameter included at runtime
initialized RT1 at 1555581638
the time in seconds, past epoch, when the blockchain was initialized
finished loading blocks RT1
informational
fAddressIndex.0/0 fSpentIndex.0/0
informational and can be ignored for now
height.0 slowflag.1 possible.1 cmp.0
informational and can be ignored for now
Querying the Blockchain Using komodo-cli
With the regtest Smart Chain operational we are prepared to execute our first API call.
Access a Daemon via komodo-cli on a Smart Chain
When using komodo-cli to access the daemon of a Smart Chain, we must add an additional argument to each terminal input.
This required argument is the name of the Smart Chain for which the user desires komodo-cli to connect. The name is provided in the same format used to launch the chain.
In our tutorial, the argument is: -ac_name=RT1
Furthermore, as we are using the regtest feature, we must also include the -regtest argument with each terminal input.
Therefore, each komodo-cli terminal input will begin with the following:
Using the getinfo API Method
The getinfo API method does not require any additional parameters when called and provides useful information about our chain.
To execute the method in the terminal we can use the komodo-cli software.
Command
Response
Note the blocks count of zero 0 and the balance sum of 0. While our regtest chain's daemon is operational, we have yet to mine the genesis block and collect the initial coin value.
Querying the Blockchain Using curl
Alternatively, we can execute the getinfo method using the Unix curl command.
Sourcing the Configuration File
The curl command will also need information about which Smart Chain daemon the user desires to connect. However, the curl command will receive these instructions in a different manner.
The user must provide the myrpcuser, myrpcpassword, and myrpcport values from the Smart Chain's configuration file.
The configuration file is automatically generated on Smart Chain creation, and is formatted for use with the Unix source command.
To import all values into our terminal process environment, execute the following:
We can test that the variables were loaded correctly with the following commands:
The terminal should return the values from the configuration file.
Executing the curl Command
With these variables set we can now easily use the curl command to execute the getinfo API method:
We execute the curl command with -s silent option; this mutes irrelevant response data.
The $rpcuser:$rpcpassword and the ...$rpcport arguments utilize our sourced environment variables.
The HTTP header -H, --data-binary, and content-type: text/plain; arguments instruct curl to reply with a json object.
Without further intervention, the returned json response will be unformatted and difficult to read.
To improve readability, the developer may optionally install and utilize the jq terminal software.
Link to download and install jq
Once installed, add a | pipe and a jq '.' reference at the end of the curl command:
This should return a well formatted json object.
Preparing Your Local Wallet
The wallet is not part of the blockchain. Rather, it is a separate application that tracks your private keys and grants access to them upon user request. This separate application is built into the Indexchain daemon and can be accessed using the API.
Common API commands include the following:
Command
Description
get a new address
get the public key of the new address; used often when developing a custom application-specific blockchain
get the private key of an address
We save details from each response, so that we may avoid continually obtaining new wallet keys.
The next two sections demonstrate how to obtain a new private key. The first section uses komodo-cli software, and the second section repeats the same API steps using the curl command.
Preparing Your Wallet Using komodo-cli
getnewaddress
To obtain a new address, we use the getnewaddress API method:
Response:
Your response will be a different address of the same format.
validateaddress
To obtain the public key, also called the "pubkey", we use the validateaddress API method.
Response:
Make a note of the pubkey value. We will use it towards the end of the tutorial.
dumpprivkey
Use the response from getnewaddress as an argument for the dumpprivkey API method.
The response is the private key for this address.
The private key should never be shared under any circumstances. We have redacted the response for this tutorial.
Preparing Your Wallet Using curl
getnewaddress
A curl command to obtain a new address using the getnewaddress API method.
Command
Response
validateaddress
A curl command to obtain the pubkey using the validateaddress API method.
Command
Response
dumpprivkey
A curl command to obtain the pubkey using the validateaddress API method.
Command
Response
Generating Blocks and Getting the New Coins
When connecting to an existing blockchain that already has a populated network of miners or stakers, the user does not need to be concerned about how blocks are generated.
However, in this tutorial we are running a regtest chain, and therefore we must instruct the daemon to generate new blocks.
This also provides us with a useful opportunity to discuss the nature of simple mining in the Indexchain ecosystem. The methods we discuss here reflect mining on a proof-of-work based Smart Chain.
The reader should be aware that Indexchain also offers proof-of-stake mining, and hybrid models that blend proof-of-work with proof-of-stake. For more information, the reader may turn to the ac_staked feature.
Here are several common API methods for mining:
Command
Description
the number of blocks to generate
query information about a block
query a transaction
In a moment, we will use these commands to generate new blocks on our regtest chain, and in the process of generating, the blockchain will create new coins.
Understanding the Coinbase Transaction
The reader should be aware of the manner in which a blockchain creates new coins.
When a blockchain initiates for the first time, and before it has mined the first block, the total sum of coins on the blockchain is always 0.
To add coins into the total coin supply, the blockchain must mint new coins. This minting process occurs in a special transaction that is included as the first transaction in each block of the blockchain.
This transaction is called the coinbase transaction.
While every other transaction on the blockchain can only take coins from the existing supply, the coinbase transaction may create new coins from nothing.
These new coins can be sent to any number of locations. The rules of the blockchain, as set by the blockchain's developer, determine how many coins are minted, and who receives the coins.
For more information about how to customize your coinbase transactions on a Indexchain Smart Chain, observe the many different customization parameters in the Antara Customizations documentation.
For example, read about ac_reward, ac_eras, ac_founders, and many others.
In our tutorial, when we mine our first block, all of the 1000 new coins we indicated will be mined in the first block's coinbase transaction. By default, these coins are distributed immediately into our own local wallet.
Generating Blocks Using komodo-cli
generate
We now generate a few blocks using the generate API method.
Command
Response
The response contains an array of blockhashes. These are the hashes of the blocks generated.
getblock
To inspect the particular information about any given block, we use the getblock API method and include our desired blockhash as an argument.
Alternatively, with getblock we can instead include the desired block height of the block we wish to inspect.
In our case, we desire to inspect the genesis block, which is the first block ever mined on our Smart Chain. Therefore, the block height will be 1.
Command
Response
Note in the response the tx value.
This value is an array containing all transactions performed within this block. Because it is the genesis block, and because we did not send any transactions on our blockchain, the only transaction is our coinbase transaction, wherein the 1000 coins were minted and sent to our local wallet.
gettransaction
To observe this transaction, we use the gettransaction API method.
Command
Response
Note that the amount value is slightly higher than 1000. This is normal. It is due to the internal mathematical complexities of a blockchain.
Generating Blocks Using curl
generate
We have already generated the genesis block. The following is a sample of using curl with the generate API method to generate 5 blocks.
<collapse-text hidden title="Response">
</collapse-text>
getblock
Here is a sample of using curl with the getblock API method on the blockhash of the genesis block.
To use the block height instead, the curl command is formatted as follows.
<collapse-text hidden title="Response">
</collapse-text>
gettransaction
Here is the curl command to retrieve the first block's coinbase transaction.
<collapse-text hidden title="Response">
</collapse-text>
Inspecting the wallet
We have generated blocks and received the value from the coinbase transactions. Now, we would like to inspect the contents of our wallet. We will execute the listunspent method for this purpose.
However, before we execute this command, the reader should familiarize themselves with the way a blockchain stores value in a wallet. The title of the technical concept to understand is, "utxo." This stands for "unspent transaction."
The way a utxo works is often difficult to understand for newcomers to blockchain technology. We have provided an article that explains this concept in more detail here, and we recommend the reader study it before proceeding.
The reader may turn to the Core Technology Discussion regarding utxos for more information.
In blockchain technology, all value is contained within utxos. Every transaction consumes a utxo and creates new utxos.
Once you are comfortably familiar with the concept, you are prepared to continue with the tutorial.
Listing Unspent Transactions Using komodo-cli
A developer should be able to easily validate ownership of a utxo, as only the owner of a utxo is able to spend it.
listunspent
For this purpose, we turn to the listunspent API method:
The response is an array of transactions ids, called txid for brevity's sake.
Listing Unspent Transactions Using curl
With curl, the terminal command for listunspent is as follows:
<collapse-text hidden title="Response">
</collapse-text>
Setting the pubkey Parameter
Observe this first txid returned from the listunspent transaction:
Notice that the address to which these 1000 coins were sent is not the address we generated earlier. Rather, it is an entirely new address. At the moment we may not mind, because the coins were sent to an address that the wallet automatically generated and which we own.
However, what if we want to control the address to which coins are sent when mining? When this is the case, we turn to the pubkey launch parameter.
The pubkey we input into this parameter can be the same pubkey we generated earlier in the tutorial.
Stopping the Daemon Using komodo-cli
To place this pubkey at startup, we must first stop the Smart Chain.
For this we use the stop API method.
Command
Response
Stopping the Daemon Using curl
Using curl to stop the daemon.
Command
Response
Restarting the Smart Chain With the pubkey Parameter
Execute the following to relaunch komodod with the pubkey we saved at the beginning of the tutorial.
Command
Now, when we generate new blocks, the coinbase transaction sends new coins to the new address associated with our pubkey.
First, we generate a new block using komodo-cli.
Response:
We can repeat the getblock method on the blockhash returned above to see the coinbase transaction.
With that coinbase transaction, we can the execute gettransaction to see the address to which the new coins were sent.
After executing these previously explained methods, here is a snippet of the final result:
Note that the address in this output is the one associated with our desired pubkey.
Closing
Some of the fundamental blockchain and API skills we have learned include the following:
How to create a new Indexchain Smart Chain
How to make a single-node regtest chain, for development purposes
How to launch with the pubkey set
How to generate new blocks
How to obtain information about blocks and transactions
The nature of a utxo
The nature of a coinbase transaction
Having completed this tutorial, the developer should be able to explore the many API methods in the Indexchain documentation.
Last updated
Was this helpful?