ABI Reference

Overview

The ABI defines the application interface interaction with everiToken blockchain. Applications can use JSON RPC to communicate with everiToken. For API references, you can view this document. This document will explain details about the abi json definition (ie. the args field you send to /v1/chain/abi_json_to_bin).

Base Types

Before describing the ABI for each action, it is necessary to introduce some base types. Base types are the basic types that EVT RPC interface supports. Their definitions are given in the table below.

Type Name Description Additional
bool 8-bits unsigned integer 0 for false, other for true
int8 8-bits signed integer
uint8 8-bits unsigned integer
int16 16-bits signed integer
uint16 16-bits unsigned integer
int32 32-bits signed integer
uint32 32-bits unsigned integer
int64 64-bits signed integer
uint64 64-bits unsigned integer
uint128 128-bits unsigned integer
percent decimal float number, should be in string representation e.g. ;;0.05
bytes binary data represented in hex format 0000abcd represents for a 64-bits binary data
string UTF-8 encoding string
public_key ECC public key with EVT prefix e.g. See #1 below
signature ECC signature e.g. See #2 below
time_point_sec ISO format time string e.g. 2018-03-02T12:00:00
name A string encoded into a 64-bits value Max length: 13 chars and value range: [0-9a-z.]
name128 A string encoded into a 128-bits value Max length: 21 chars and value range: [0-9A-Za-z.-]
asset A floating number value with symbol as suffix See asset type section below
symbol Represents a token and contains precision and name. See symbol type section below
authorizer_ref Reference to a authorizer Valid authorizer including an account, a group or special OWNER group
group Authorize group tree See group type section below
address Address type See address type section below
evt_link EVT-Link type Refer to this document for more detail
  • #1: EVT8MGU4aKiVzqMtWi9zLpu8KuTHZWjQQrX475ycSxEkLd6aBpraX
  • #2: SIG_K1_JzrdhWW46N5nFUZzTUmhg2sK4nKNGktPz2UdRz9bSAP5pY4nhicKWCuo6Uc6U7KBBwD8VfjsSxzHWT87R41xMaubnzMq8w

ABIs are built on Base Types given above.

asset Type

asset type is composed of two parts: the number part representing price or volume, and the symbol part describing the type name of asset.

The number part is a number containing a . which introduces its precision. The precision is determined by the digits after the .. That is, 0.300 has the precision of 3, while 0.3 only has the precision of 1. The precision of an asset should be less than 18.

The symbol part introduces the symbol ID, which is an integer number representing one unique fungible token symbol.

Only assets of the same type can be added up. The EVT an asset type with the precision of 5 and 1 as its symbol ID. Therefore, 12.00000 S#1 is a valid EVT asset, but 12.000 S#1, 12 S#1 or 12.0000 S#1 are invalid EVT asset due to the wrong precision.

symbol Type

symbol type is the symbol part of the asset type. It represents a token and contains precision and a unique ID. Precision is a number and should be less than 18, and a symbol ID is a unique integer number.

For example, 12.00000 S#1 is a valid EVT asset, and it has the precision of 5 and '1' its symbol ID. Its symbol expression is 5,S#1.

Then 7,S#123 represents an asset symbol with a precision of 7 and '123' as its symbol ID.

authorizer_ref Type

The authorizer_refis a reference to an authorizer. The current valid authorizer types include an account, a group, or a special OWNER group (aka. owner field of a token). All three formats are described below:

  1. Refers to an account named 'evtaccount'; it starts with "[A]": [A] evtaccount.
  2. Refers to a group named 'evtgroup'; it starts with "[G]": [G] evtgroup.
  3. Refs to OWNER group: [G] .OWNER.

address Type

address type is used to replace old public key addresses, and it has three possible types:

  • public key: same as the old public key address
  • reserved: 'EVT00000000000000000000000000000000000000000000000000', this type is used for representing destroyed token and cannot-updated group.
  • generated: generated from three values: prefix(name), key(name128), nonce(uint32), this type is designed for certain special usage.

All addresses have a length of 53, have a prefix of 'EVT', and can be distinguished from public key type by checking to see if the forth char is '0' or not. '0' cannot be used in normal public key representation.

There are many generated address usages in everiToken; below are some common conditions:

Domain pay address

Used in situations where a domain can pay for the transaction fees of its tokens. You can get this address by calling /v1/evt/get_domain API.

Fungible reserved address

Currently initial fungible tokens are stored in a special fungible reserved address, and issuefungible will transfer fungible tokens from the reserved address to the issue address. You can get this address by calling /v1/evt/get_fungible API.

Passive bonus fund pool address

If one fungible token is registered with a passive bonus, then all of the transaction fees will be put into this address temporarily. You can get this address by calling /v1/evt/get_fungible_psvbonus

group Type

An authorized group is represented by a tree structure, where each leaf node is a reference to an authorizer and attached with a weight, while non-leaf nodes behave as a switch. It has a threshold value and is only turned on if the sum of weights of all the authorized child nodes exceeds its threshold value. So, a non-leaf node also has a weight value, and a root node only has a threshold value.

A sample group is defined as below:

{
    "name": "testgroup",
    "key": "EVT6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
    "root": {
        "threshold": 6,
        "nodes": [
            {
                "threshold": 1,
                "weight": 3,
                "nodes": [
                    {
                        "key": "EVT6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
                        "weight": 1
                    },
                    {
                        "key": "EVT8MGU4aKiVzqMtWi9zLpu8KuTHZWjQQrX475ycSxEkLd6aBpraX",
                        "weight": 1
                    }
                ]
            },
            {
                "key": "EVT8MGU4aKiVzqMtWi9zLpu8KuTHZWjQQrX475ycSxEkLd6aBpraX",
                "weight": 3
            },
            {
                "threshold": 1,
                "weight": 3,
                "nodes": [
                    {
                        "key": "EVT6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
                        "weight": 1
                    },
                    {
                        "key": "EVT8MGU4aKiVzqMtWi9zLpu8KuTHZWjQQrX475ycSxEkLd6aBpraX",
                        "weight": 1
                    }
                ]
            }
        ]
    }
}

This sample group has the name testgroup and key EVT6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV. The threshold of the root node is 6, and it has 3 child nodes with a weight represented by a value of 3.

The key of group is an address type. So it can be referred to as a reserved type address, meaning that this group cannot be updated.

Typedefs

Normally typedef is a keyword in C and C++. It shares the same meaning here. It means that each type of the following is the same type as the original, or it can be considered an alias of the original type.

Any type with [] as a suffix represents an array type. For example, int32[] defines an array type with every single element in that array belonging to type int32. A type with ? as a suffix means that it is an optional type whose value may be undefined.

Typedef Type Original Type
user_id public_key
user_list user_id[]
group_key public_key
weight_type uint16
permission_name name
action_name name
domain_name name128
domain_key name128
group_name name128
token_name name128
account_name name128
proposal_name name128
fungible_name name128
symbol_name name128
balance_type asset
symbol_id_type uint32
group_def group
meta_key name128
meat_value string
meta_list meta[]
address_list address[]

Enums

Enum is an enumeration type containing many fields. Each field is represented as one option. When setting the value of enum type, you can treat enum as a string type, but the valid values should be within fields.

passive_method_type Enum

{
    within_amount,
    outside_amount
}

Structures

A structure is a complex type consisting of base types, enums, and variants. Below are all of the structures used in everiToken’s ABI interface.

void Struct

{}

key_weight Struct

{
    "key": `public_key`,
    "weight": `weight_type`
}

authorizer_weight Struct

{
    "ref": `authorizer_ref`,
    "weight": `weight_type`
}

permission_def Struct

{
    "name": `permission_name`,
    "threshold": `uint32`,
    "authorizers", `authorizer_weight[]`
}

locknft_def Struct

{
    "domain": `domain_name`,
    "names": `token_name[]`
}

lockft_def Struct

{
    "from": `address`,
    "amount": `asset`
}

lock_condkeys Struct

{
    "threshold": `uint16`,
    "cond_keys": `public_key[]`
}

dist_stack_receiver Struct

{
    "threshold": `asset`
}

dist_fixed_rule Struct

{
    "receiver": `dist_receiver`,
    "amount": `asset`
}

dist_precent_rule Struct

{
    "receiver": `dist_receiver`,
    "percent": `percent`
}

passive_method Struct

{
    "action": `name`,
    "method": `passive_method_type`
}

Variants

Variants are special types that can be one of multiple determinate types. When setting the variant variable, it can be treated as an object with two fields: type and data. type is an enum field that indicates the option, and data contains the instance data.

lock_asset Variant

{
    "tokens": `locknft_def`,
    "fungible": `lockft_def`
}

lock_condition Variant

{
    "cond_keys": `lock_condkeys`
}

lock_aprvdata Variant

{
    "cond_key": `void`
}

dist_receiver Variant

{
    "address": `address`,
    "ftholders": `dist_stack_receiver`
}

dist_rule Variant

{
    "fixed": `dist_fixed_rule`,
    "percent": `dist_percent_rule`,
    "remaining_percent": `dist_percent_rule`
}

Actions

Below are all of the actions supported in everiToken v3.0.

newdomain Action

Create a new domain with a name and permission set consisting issue, transfer and manage.

{
    "name": `domain_name`,
    "creator": `user_id`,
    "issue", `permission_def`,
    "transfer", `permission_def`,
    "manage", `permission_def`
}

updatedomain Action

Update a domain with new permissons, issue, transfer and manage are all optional.

{
    "name": `domain_name`,
    "issue", `permission_def?`,
    "transfer", `permission_def?`,
    "manage", `permission_def?`
}

issuetoken Action

Issue one or more tokens within a specific domain; the default owners are also specified.

{
    "domain": `domain_name`,
    "names": `token_name[]`,
    "owner": `address_list`
}

transfer Action

Transfer one token within a specific domain to new owners.

{
    "domain": `domain_name`,
    "name": `token_name`,
    "to": `address_list`,
    "memo": `string`
}

destroytoken Action

Destroy one token (aka. Cannot be used anymore).

{
    "domain": `domain_name`,
    "name": `token_name`
}

newgroup Action

Create a new group with a name.

group_def is a special type defined in Base Types section.

{
    "name": `group_name`,
    "group": `group_def`
}

updategroup Action

Update a specific group's structure.

{
    "name": `group_name`,
    "group": `group_def`
}

newfungible Action

Create a new fungible token definition with a specific total supply (supply cannot be zero).

{
    "name": `fungible_name`,
    "sym_name": `symbol_name`,
    "sym": `symbol`,
    "creator": `user_id`,
    "issue": `permission_def`,
    "manage": `permission_def`,
    "total_supply": "asset"
}

updfungible Action

Update a fungible token’s definition.

{
    "sym_id": `symbol_id_type`,
    "issue": `permission_def?`,
    "manage": `permission_def?`
}

issuefungible Action

Issue fungible tokens.

{
    "address": `address`,
    "number": `asset`,
    "memo": `string`
}

transferft Action

Transfer fungible tokens between addresses.

{
    "from": `address`,
    "to": `address`,
    "number": `asset`,
    "memo": `string`
}

recycleft Action

Recycle fungible tokens.

{
    "address": `address`,
    "number": `asset`,
    "memo": `string`
}

destroyft Action

Destroy fungible tokens.

{
    "address": `address`,
    "number": `asset`,
    "memo": `string`
}

evt2pevt Action

Convert EVT fungible tokens to Pined EVT(symbol: S#2) fungible tokens.

This operation is irreversible and to address is not limited to the giver.

{
    "from": `address`,
    "to": `address`,
    "number": `asset`,
    "memo": `string`
}

addmeta Action

Add new metadata to one domain, group, token, or fungible token.

Creator is authorizer_ref which means that the creator can be one account (aka. public key) or one group. It needs to be the creator or take part in the authority tree.

{
    "key": `meta_key`,
    "value": `meta_value`,
    "creator": `authorizer_ref`
}

domain and key for different type:

Type domain key
domain domain_name .meta
group .group group_name
token domain_name token_name
fungible .fungible symbol_id_type

newsuspend Action

Add new suspended transaction (In-chain deferred signing transactions)

trx should be a valid transaction definition.

{
    "name": `proposal_name`,
    "proposer": `user_id`,
    "trx": `transaction`
}

aprvsuspend Action

Approve one suspend transaction

signatures are the signatures signed for the suspended transaction. The keys used are also the required keys when authorizing a suspended transaction.

{
    "name": `proposal_name`,
    "signatures": `signature[]`
}

cancelsuspend Action

Cancel one suspend transaction

Only the proposer can cancel his/her proposed suspended transaction.

{
    "name": `proposal_name`
}

execsuspend Action

Execute one suspend transaction

The executor must be one of the valid authorizers in order to authorize the suspended transaction.

{
    "name": `proposal_name`,
    "executor": `user_id`
}

everipass Action

Use this action to execute everiPass.

{
    "link": `evt_link`
}

everipay Action

Use this action to execute everiPay.

{
    "link": `evt_link`,
    "payee": `address`,
    "number": `asset`

}

newlock Action

Propose a new lock assets proposal.

{
    "name": `proposal_name`,
    "proposer": `user_id`,
    "status": `lock_status`,
    "unlock_time": `time_point_sec`,
    "deadline": `time_point_sec`,
    "assets": `lock_asset[]`,
    "condition": `lock_condition`,
    "succeed": `address[]`,
    "failed": `address[]`
}

aprvlock Action

Approve a lock assets proposal.

{
    "name": `proposal_name`,
    "approver": `user_id`,
    "data": `lock_aprvdata`
}

tryunlock Action

This action is used to try to unlock a lock assets proposal. If all of the conditions are satisfied, the proposal will be unlocked. If not, the proposal may remain locked if the time deadline has not been exceeded. Otherwise, it will result in a failed state.

{
    "name": `proposal_name`,
    "executor": `user_id`
}

setpsvbonus Action

Set a passive bonus to a fungible token.

{
    "sym": `symbol`,
    "rate": `percent`,
    "base_charge": `asset`,
    "charge_threshold": `asset?`,
    "minimum_charge": `asset?`,
    "dist_threshold": `asset`,
    "rules", `dist_rule[]`,
    "methods": `passive_method[]`
}

distpsvbonus Action

Start a new distribution of passive bonuses for a fungible token.

{
    "sym": `symbol`,
    "deadline": `time_point`,
    "final_receiver": `address?`
}

paybonus Action

pay the fee of bonus

{
    "payer": `address`,
    "amount": `asset`
}

paycharge Action

pay charge

{
    "payer": `address`,
    "charge": `uint32`
}



Continue Reading: API Reference