On this page

latest contributor to this doc

Last Edit:


Advanced Series — Preparing for Heir Development

This tutorial in the series assists the reader in preparing to later build a full simplified prototype of the default Heir Antara Module.

The primary aim for buildling the Heir prototype is to give the developer direct engagement with Antara Module development, with a focus on the CryptoConditions (CC) aspects. This process will give the developer a better grasp of the broad potential of the Antara framework.

Furthermore, in the process of completing this tutorial the developer will learn how the source code is organized.

To gain an idea of the intended result, read the introduction of the Heir Module API. (Read until the start of the section named Heir Module Flow and then pause.)

Link to Introduction to the Heir Antara Module

The basic concept to understand is that the Heir module allows the owner of a Smart Chain digital asset to designate an inheritor of the asset, should the owner become inactive on the chain.

In terms of design, this is a relatively straightforward Antara Module, which is one reason we use it here.

Before we begin the development process, it may be helpful to first experiment with the flow of RPC commands for the existing Heir module.

This section is optional, but recommended.

At this point in the tutorial series, the reader can either create a new default Smart Chain to test the Heir Module, or they may use an existing Smart Chain, such as DOC.

Link to instructions to create a new default Smart Chain.

The reader will need to create a new default Smart Chain either way as a part of the tutorial, but if the reader chooses to use the DOC Smart Chain for this optional step, the reader has the opportunity to observe another Antara Module in action. This presents a learning opportunity.

The module we refer to here is the Faucet Antara Module

The Faucet Module allows a user to tap into existing funds on a public Smart Chain. This module provides a simple example of the nature of an Antara Module for our study.

Faucet allows a user to lock an arbitrary amount of funds within an Antara address. Other users on the network are able to withdraw funds from this Antara address in small portions. To prevent spam requests, Faucet requires a small amount of proof-of-work from the requesting user's node.

From this outline, we observe the basic business logic of the Faucet module. The module involves storing funds in a designated address, the creation of a faucet that can disburse funds, and the ability to limit the rate at which funds are withdrawn.

Compare this to our desired Heir module. The Heir module's business logic must allow a designated address the ability to inherit designated blockchain funds.

In both cases, the module's business logic is bound to transactions.

The live community test chain, DOC, has the Heir Module enabled and can serve the purpose of providing a live demonstration.

Launch the chain as follows.

./komodod -pubkey=$pubkey  -ac_name=DOC -ac_supply=90000000000 -ac_reward=100000000 -ac_cc=3 -ac_staked=10 -addnode= -addnode= &

Use the following guide to create an Antara pubkey and address on the DOC Smart Chain.

Link to Antara pubkey creation guide

To obtain funds on the DOC Smart Chain we utilize the Faucet Antara Module.

./komodo-cli -ac_name=DOC faucetget

This returns a raw transaction that you must now broaadcast using sendrawtransaction

Wait a few moments, and then use the getinfo method to verify that your wallet now contains DOC funds.

With funds in your wallet, you are prepared to experiment with the API commands available in the Heir Module Flow section. We recommend experimenting with each command until you have executed each at least once.

Link to Heir Module Flow

Transactions are a data source for Antara-based software.

Transactions can store data in multiple forms. In the simplest form, transaction data records the movement of coins from one address to another. However, blockchain transactions are capable of storing additional data beyond simple coin movement.

When we desire to place additional data into a transaction, we place this data into an OP_RETURN, or "opreturn" for short.

Observe the following transaction data structure for the existing Heir module:

./komodo-cli -ac_name=HELLOWORLD heirfund 0 5 MyDogHeir 037736c263991316c6a23397a982a1f8c18ae8642e944448162a93a824c31f9299 100 'http://billionaire.com/mywill md5=5385639869'

The opreturn is the last output in a transaction, and this output is never spendable under any circumstances. The opreturn is the location where all Antara Module data is stored. We will demonstrate how this is accomplished further on.

The opreturn vout contains two key-value pairs that are related to each other, asm and hex. The first, asm, is simply a less encoded version of the hex value.

In the above example data structure, note how the value for the key, asm, begins with OP_RETURN ... , and is followed by additional hex-encoded data. The additional hex-encoded data is arbitrary, and can be used for any purposes a developer sees fit.

Taking the value in the fully encoded key-value pair, hex, here is an approximate breakdown of the data.

Hex ValueTranslation
4c85Encoded length of the following data. This value is not a string, the value is encoded in the Smart Bitcoin variable length format, and the value is not directly readable.
eaStands for "EVAL_HEIR". The eval code here tells the daemon that this is an Antara Module, and that the specific module is HEIR
46Stands for "F", which is a letter marker to indicate that this Heir transaction is a "Funding" transaction
210...The remaining portion of the hex encoded data is not related to the core software, but rather to the arbitrary data designed by the developer. Maximum data length is 10000 bytes

In all modules, some of the hex-encoded data can be decoded using the decodeccopret command on the data contained in the hex key-value pair. In our example, the decoded data is as follows.

  "result": "success",
  "OpRets": [
      "eval_code": "EVAL_HEIR",
      "function": "F"

When an Antara Module instance begins its life cycle an initial transaction is created. In our example, the transaction we see above is an initial transaction of a full, non-simplified Heir module.

Note that the transaction takes value from normal inputs and sends it to CC outputs, as indicated in the type key-value pair.

The important aspect to note here is that an initial transaction of a module instance typically takes value from normal inputs and sends it to CC outputs.

As time progresses, more transactions on the Smart Chain are performed under this module instance. Each of the module instance's transactions spends from the previous transaction outputs associated with the instance and creates new unspent transactions. This process effectively creates a linked-list data structure.

With each transaction, the opreturn output is never spent, and remains in the blockchain as a source of Antara Module data (read only).

Link to Next Tutorial in Advanced Series