Anatha Core Documentation

Anatha documentation

Tendermint & Cosmos

The core blockchain part for the Anatha Blockchain will be implemented with Tendermint and Cosmos SDK. The Tendermint Core handles executing the consensus engine and managing the P2P connectivity layer. As such, Tendermint doesn’t know anything about the transactions that are being executed. The transaction validity checks and transaction execution is conducted at the Cosmos SDK layer in separate functionality based state machines called modules.

Before the raw bytes that Tendermint works with get to the dedicated modules, they need to be processed by the Base Application. The Base Application is in charge for decoding the raw bytes to meaningful data and routing the transaction to the respective model for processing. The goal of the Base Application is to provide a secure interface between the store and the extensible state machine while defining as little about the state machine as possible.

Core modules

Auth module

Description

The auth module is responsible for specifying the base transaction and account types for an application. It contains the ante handler, where all basic transaction validity checks (signatures, nonces, auxiliary fields) are performed, and exposes the account keeper, which allows other modules to read, write, and modify accounts.

Queries

Query account

Path: custom/auth/account

{

Address: string

}

anathacli query auth account <address> [flags]

Parameters

max_memo_characters (uint64)

Maximum number of characters in the memo field.

tx_sig_limit (uint64)

Transaction signature limit.

tx_size_cost_per_byte (uint64)

Transaction cost per byte.

sig_verify_cost_ed25519 (uint64)

Signature verification cost for ed25519.

sig_verify_cost_secp256k1 (uint64)

Signature verification cost for secp256k1.

Bank module

Description

The bank module is responsible for handling coin transfers between accounts and tracking special-case pseudo-transfers which must work differently with particular kinds of accounts (notably bonding/unbonding for savings accounts). It exposes several interfaces with varying capabilities for secure interaction with other modules which must alter user balances.

Transactions

Send tokens

Send an arbitrary amount of tokens from one account to another. This transaction will fail if the sender doesn't have enough funds to cover the transaction fees or the sending amount. If the recipient doesn't have an account, it'll be created.

{

type: "cosmos-sdk/MsgSend"

value: {

from_address: AccAddress

to_address: AccAddress

amount: Coins

}

anathacli tx send <from_address> <to_address> <amount> [flags]

Send tokens from multiple accounts to multiple accounts

Send an arbitrary amount of tokens from multiple accounts to multiple accounts. This transaction will fail if senders don't have enough funds to cover the transaction fees or the sending amount. If one of the recipients doesn't have an account, it'll be created. This transaction requires a signature from all accounts in the inputs list (multisig).

{

type: "cosmos-sdk/MsgMultiSend"

value: {

inputs: [{

address: AccAddress

coins: Coins

}]

outputs: [{

address: AccAddress

coins: Coins

}]

}

Queries

Query account balances

Path: custom/bank/balances

{

Address: string

}

Parameters

sendenabled (bool)

Flag that denotes whether transfers are enabled or not. (default: true)

Supply module

Description

The supply module passively tracks the total supply of coins within a chain, provides a pattern for other modules to hold/interact with coins and introduces a security invariant check to verify a chain's total supply.

Queries

Query total supply

Path: custom/supply/total_supply

{

Page: number

Limit: number

}

anathacli query supply total [flags]

Query supply of a given denom

Path: custom/supply/supply_of

{

Denom: string

}

anathacli query supply total <denom> [flags]

Staking module

Description

The module enables the blockchain to support a Proof-of-Stake system. In this system, holders of the native staking token of the chain can become validators and stake tokens to ultimately determine the effective validator set for the system. The specific difference between other PoS networks is that in this system all validators will have the same voting power that equals their stake. This mechanism is only available to HRA holders.

Transactions

Create a new validator

Create a new validator on the blockchain by providing all required details.

{

type: "cosmos-sdk/MsgCreateValidator"

value: {

description: {

moniker: string

identity: string

website: string

security_contact: string

details: string

}

delegator_address: AccAddress

validator_address: ValAddress

pubkey: PubKey

value: Coins

}

anathacli tx astaking create-validator --details <details> --identity <identity> --moniker <moniker> --website <website> --security-contact <security_contanct> --pubkey <validator_pubkey> --from <address> [flags]

Edit validator

Edit validator details.

{

type: "cosmos-sdk/MsgEditValidator"

value: {

description: {

moniker: string

identity: string

website: string

security_contact: string

details: string

}

validator_address: ValAddress

}

anathacli tx astaking edit-validator --details <details> --identity <identity> --moniker <moniker> --website <website> --security-contact <security_contanct> --from <address> [flags]

Top up tokens

Delegate slashed tokens to your validator. This transaction can only be invoked by validator's operator and it's used for topping up validator's stake after slashing.

{

type: "cosmos-sdk/MsgDelegate"

value: {

delegator_address: AccAddress

validator_address: ValAddress

}

anathacli tx astaking delegate <validator_address> --from <address> [flags]

Undelegate tokens

Undelegate tokens from a validator. This transaction can only be invoked by validator's operator and it will unbond all tokens from the validator.

{

type: "cosmos-sdk/MsgUndelegate"

value: {

delegator_address: AccAddress

validator_address: ValAddress

}

anathacli tx astaking unbond --from <address> [flags]

Queries

Query validators

Path: custom/astaking/validators

{

Page: number

Limit: number

Status: string

}

anathacli query astaking validators [flags]

Query single validator

Path: custom/astaking/validator

{

ValidatorAddr: ValAddress

}

anathacli query astaking validator <validator_address> [flags]

Query validator delegations

Path: custom/astaking/validatorDelegations

{

ValidatorAddr: ValAddress

}

anathacli query astaking delegations-to <validator_address> [flags]

Query validator unbonding delegations

Path: custom/astaking/validatorUnbondingDelegations

{

ValidatorAddr: ValAddress

}

anathacli query astaking unbonding-delegations-from <validator_address> [flags]

Query staking pools

Path: custom/astaking/pool

anathacli query astaking pool [flags]

Query Staking parameters

Path: custom/astaking/parameters

anathacli query astaking params [flags]

Query historical info

Path: custom/astaking/historicalInfo

{

Height: number

}

anathacli query astaking historical-info <height> [flags]

Parameters

unbonding_time (time.Duration)

Time duration of unbonding. (default: 21 days)

max_validators (uint16)

Maximum number of validators. (default: 100)

max_entries (uint16)

Maximum entries for unbonding delegation (per pair). (default: 7)

historical_entries (uint16)

Number of historical entries to persist. (default: 0)

bond_denom (string)

Bondable coin denomination. (default: pin)

Slashing module

Description

The slashing module disincentivizes any attributable action by a protocol-recognized actor with value at stake by penalizing them ("slashing"). Penalties include:

Burning some amount of their stake
Removing their ability to vote on future blocks for a period of time

Transactions

Unjail validator

If the validator is jailed for downtime, after the configurable jail duration passes, it can send this transaction to get unjailed and return to the validator set. If the validator is jailed for equivocation, it can't be unjailed.

{

type: "cosmos-sdk/MsgUnjail"

value: {

address: ValAddress

}

anathacli tx slashing unjail --from <address> [flags]

Queries

Query Slashing parameters

Path: custom/slashing/parameters

anathacli query slashing params [flags]

Query Slashing signing info

Path: custom/slashing/signingInfo

{

ConsAddress: ConsAddress

}

anathacli query slashing signing-info <validator_cons_pub_key> [flags]

Parameters

signed_blocks_window (int64)

A window of signed blocks used for checking validator activity. (default: 100)

min_signed_per_window (sdk.Dec)

Minimum percentage of signed blocks per window. (default: 0.5)

downtime_jail_duration (time.Duration)

Jail duration for validator downtime. (default: 600 seconds)

slash_fraction_double_sign (sdk.Dec)

Fraction of the total validator stake that will be burned if equivocation occurs. (default: 1/20)

slash_fraction_downtime (sdk.Dec)

Fraction of the total validator stake that will be burned if the validator didn't sign the minimum amount of blocks per window. (default: 1/100)

Mint module

Description

The minting mechanism was designed to generate an inflation rate in the system. The inflation rate is initially set at 1% annually and calculated per block. The module supports having a dynamic inflation rate based on several parameters but starts off with a fixed 1% annual inflation rate which can be changed through governance proposals or network upgrade procedures.

Queries

Query Mint parameters

Path: custom/mint/parameters

anathacli query mint params [flags]

Query minter state

Path: custom/mint/minter

anathacli query fee minter [flags]

Parameters

per_second_inflation_rate (sdk.Dec)

Inflation rate per second. (default: 0.000000000315306958)

mint_denom (string)

Token denom for minted tokens. (default: pin)

Governance module

Description

The Governance module enables the blockchain to support an on-chain governance system. Before evolving to a decentralized governance system, this module will implement governance procedures based on a threshold on-chain multisignature model, meaning that only participants that are registered in the genesis block would be able to create governance proposals and vote. Utilizing the mechanism of the Upgrade module, the Governance module can be self-updated to decentralized governance.

Transactions

Submit proposal

Transaction that allows governors to submit a new proposal. Proposal content has to be registered in the governance module router.

{

type: "governance/MsgSubmitProposal"

value: {

proposer: AccAddress

content: Content

}

anathacli tx governance submit-proposal --from <address> [flags]

Vote

Vote on a given proposal. Only Yes and No votes are supported.

{

type: "governance/MsgVote"

value: {

proposal_id: number

voter: AccAddress

option: VoteOption

}

anathacli tx governance vote <proposal_id> <vote_option> --from <address> [flags]

Expedite voting

If the proposal has enough votes and the voting outcome can't change anymore with further votes, the voting process can be expedited. This transaction can be invoked to try to manually expedite the voting process.

{

type: "governance/MsgExpedite"

value: {

proposal_id: number

sender: AccAddress

}

anathacli tx governance expedite <proposaL_id> --from <address> [flags]

Proposals

New text proposal

This proposal allows governors to submit a pure textual proposal that has no action.

{

type: "governance/TextProposal"

value: {

title: string

description: string

}

anathacli tx governance submit-proposal --description <description> --title <title> --type text --from <address> [flags]

Add governor

This proposal allows governors to add a new governor to the list of governors. This proposal will pass only if the vote is unanimous.

{

type: "governance/AddGovernorProposal"

value: {

title: string

description: string

governor: AccAddress

}

anathacli tx governance submit-proposal add-governor <proposal_file.json> --from <address> [flags]

Remove governor

This proposal allows governors to remove an existing governor from the governors list. This proposal will pass only if all except the given governor vote yes.

{

type: "governance/RemoveGovernorProposal"

value: {

title: string

description: string

governor: AccAddress

}

anathacli tx governance submit-proposal remove-governor <proposal_file.json> --from <address> [flags]

Queries

Query Governance parameters

Path: custom/governance/params

anathacli query governance params [flags]

Query proposals

Path: custom/governance/proposals

anathacli query governance proposals [flags]

Query proposal by id

Path: custom/governance/proposal/:id

anathacli query governance proposal <id> [flags]

Query votes by proposal id

Path: custom/governance/votes/:id

anathacli query governance votes <proposal_id> [flags]

Query single vote

Path: custom/governance/vote/:id/:address

anathacli query governance vote <proposal_id> <address> [flags]

Query governors

Path: custom/governance/governors

anathacli query governance governors [flags]

Parameters

voting_params (VotingParams)
- voting_period (time.Duration)

Duration of the proposal voting period. (default: 24 hours)

tally_params (TallyParams)
- quorum (sdk.Dec)

Proposal voting quorum. (default: 0.334)

- threshold (sdk.Dec)

Proposal voting threshold. (default: 0.5)

Params module

Description

The params module provides a globally available parameter store which can be used to configure different modules. It can support permissioned parameter store access.

Proposals

Parameter change proposal

This proposal allows governors to modify any configurable parameters defined in other core modules by specifying the parameter subspace, key and new value. New value has to be a JSON encoded string.

{

type: "cosmos-sdk/ParameterChangeProposal"

value: {

title: string

description: string

changes: [{

subspace: string

key: string

value: string

}]

}

anathacli tx governance submit-proposal param-change <proposal_file.json> --from <address> [flags]

Crisis module

Description

The crisis module halts the blockchain under the circumstance that a blockchain invariant is broken.

Transactions

Invariant verification

If there's a reason to believe that a certain invariant is broken, this transaction can be invoked by paying the configurable fixed fee amount. If the invariant is broken, the chain will halt.

{

type: "cosmos-sdk/MsgVerifyInvariant"

value: {

sender: AccAddress

invariant_module_name: string

invariant_route: string

}

anathacli tx crisis invariant-broken <module_name> <invariant_route> --from <address> [flags]

Parameters

ConstantFee (sdk.Coin)

Fixed fee amount for the invariant check transaction. (default: 50000000000000pin)

Evidence module

Description

The Evidence module allows the submission and handling of arbitrary evidence of misbehavior such as equivocation and counterfactual signing.

Transactions

Submit evidence

Submit evidence of validator misbehaviour, i.e. equivocation.

{

type: "cosmos-sdk/MsgSubmitEvidence"

value: {

evidence: Evidence

submitter: AccAddress

}

Queries

Query Evidence parameters

Path: custom/evidence/parameters

anathacli query evidence params [flags]

Query evidence

Path: custom/evidence/evidence

anathacli query evidence evidence <hash> [flags]

Query all evidences

Path: custom/evidence/all_evidence

anathacli query evidence evidence [flags]

Parameters

max_evidence_age (time.Duration)

Maximum age of valid evidence.

Upgrade module

Description

The Upgrade module facilitates smoothly upgrading a live chain to a new (breaking) software version. It accomplishes this by providing a BeginBlocker hook that prevents the blockchain state machine from proceeding once a pre-defined upgrade block time or height has been reached The module does not assume anything regarding how governance decides to do an upgrade, but just the mechanism for coordinating the upgrade safely. Without software support for upgrades, upgrading a live chain is risky because all of the validators need to pause their state machines at exactly the same point in the process. If this is not done correctly, there can be state inconsistencies which are hard to recover from.

Proposals

New software upgrade proposal

Governors can propose a blockchain software upgrade to a new version at given block height.

{

type: "upgrade/SoftwareUpgradeProposal"

value: {

title: string

description: string

plan: [{

name: string

height: number

info: string

}]

}

anathacli tx governance submit-proposal software-upgrade <proposal_file.json> --from <address> [flags]

Queries

Query current upgrade

Path: custom/upgrade/current

anathacli query upgrade current [flags]

Query applied upgrades

Path: custom/upgrade/applied/:name

anathacli query upgrade applied <name> [flags]

HRA module

Description

This module contains all of the logic linking an Anatha address to one or more human-readable addresses (HRAs) and their metadata, which includes multi-currency wallets and other crypto addresses.

Transactions

Register a new HRA

Register a new HRA by providing the name and the owner (signer). The transaction will fail if the name is already registered, or if the owner doesn't have enough tokens to cover the name registration fee and respective system fees.

{

type: "hra/Register"

value: {

name: string

owner: AccAddress

}

anathacli tx hra register <name> --from <address> [flags]

Renew a HRA

Renew an existing HRA. HRA can only be renewed by its owner. The transaction will fail if the name is not registered, if the specified owner doesn't own the name, or if the owner doesn't have enough tokens to cover the name renewal fee and respective system fees.

{

type: "hra/Renew"

value: {

name: string

owner: AccAddress

}

anathacli tx hra renew <name> --from <address> [flags]

Set HRA price

If users want to sell their HRA, they have to set a price. HRA is considered for sale if the price is greater than zero. HRA price can only be set by its owner. The transaction will fail if the name is not registered or if the specified owner doesn't own the name.

{

type: "hra/SetPrice"

value: {

name: string

owner: AccAddress

price: Coins

}

anathacli tx hra set-price <name> <price> --from <address> [flags]

Buy a HRA

This transaction allows users to purchase HRAs that are marked for sale. The transaction will fail if the name is not registered or if it's not for sale.

{

type: "hra/Buy"

value: {

name: string

buyer: AccAddress

}

anathacli tx hra buy <name> --from <address> [flags]

Delete a HRA

Delete an existing HRA. The transaction will fail if the name is not registered or if it's not owned by the specified owner.

{

type: "hra/Delete"

value: {

name: string

owner: AccAddress

}

anathacli tx hra delete <name> --from <address> [flags]

Transfer a HRA

Transfer an existing HRA to another user. The transaction will fail if the name is not registered or if it's not owned by the specified owner. If the new owner doesn't have an account on the blockchain, the account will be created.

{

type: "hra/Transfer"

value: {

name: string

owner: AccAddress

new_owner: AccAddress

}

anathacli tx hra transfer <name> <new_owner> --from <address> [flags]

Register a blockchain address

Register a new blockchain address by providing the blockchain id, address' index and the blockchain address. The provided blockchain id has to be on the list of allowed blockchain ids.

{

type: "hra/RegisterAddress"

value: {

owner: AccAddress

blockchain_id: string

index: string

blockchain_address: string

}

anathacli tx hra register-address <blockchain_id> <index> <blockchain_address> --from <address> [flags]

Remove a blockchain address

Remove an existing blockchain address associated with the owner address. This transaction will fail if the blockchain address does not exist.

{

type: "hra/RemoveAddress"

value: {

owner: AccAddress

blockchain_id: string

index: string

}

anathacli tx hra remove-address <blockchain_id> <index> --from <address> [flags]

Remove all blockchain addresses

Remove all blockchain addresses registered by the owner.

{

type: "hra/RemoveAllAddresses"

value: {

owner: AccAddress

}

anathacli tx hra remove-all-addresses --from <address> [flags]

Proposals

Register blockchain id

Governors can propose the addition of a new blockchain id to the list of allowed blockchain ids.

{

type: "hra/RegisterBlockchainIdProposal"

value: {

title: string

description: string

blockchain_id: string

}

anathacli tx governance submit-proposal register-blockchain-id <proposal_file.json> --from <address> [flags]

Remove blockchain id

Governors can propose the removal of a blockchain id from the list of allowed blockchain ids.

{

type: "hra/RemoveBlockchainIdProposal"

value: {

title: string

description: string

blockchain_id: string

}

anathacli tx governance submit-proposal remove-blockchain-id <proposal_file.json> --from <address> [flags]

Queries

Resolve HRA

Path: custom/hra/resolve/:name

anathacli query hra resolve <name> [flags]

Query names owned by an address

Path: custom/hra/names/:address

anathacli query hra names <address> [flags]

Query blockchain address

Path: custom/hra/address/:name/:blockchain_id/:index

anathacli query hra address <name> <blockchain_id> <index> [flags]

Query HRAs owned by an address

Path: custom/hra/name-infos/:address

anathacli query hra name-infos <address> [flags]

Query registered blockchain ids

Path: custom/hra/registered-blockchain-ids

anathacli query hra registered-blockchain-ids [flags]

Query address credits

Path: custom/hra/address-credits/:address

anathacli query hra address-credits <address> [flags]

Query blockchain addresses owned by an address

Path: custom/hra/blockchain-addresses/:address

anathacli query hra blockchain-addresses <address> [flags]

Query HRA parameters

Path: custom/hra/parameters

anathacli query hra params [flags]

Query module accounts

Path: custom/hra/module/:name

anathacli query hra module <name> [flags]

Parameters

nameinfo_duration (time.Duration)

Duration of HRA registration (default: 1 year)`

nameinfo_max_duration (time.Duration)

Maximum HRA duration (default: 3 years)

registration_fee (sdk.Coins)

HRA registration fee in pin (default: 100000000pin - 1 ANATHA)

renewal_fee (sdk.Coins)

HRA renewal fee in pin (default: 100000000pin - 1 ANATHA)

address_credits (sdk.Int)

Amount of address credits given to the user when registering the first HRA. (default: 20)

address_registration_fee (sdk.Coins)

Address registration fee in pin, after the credits are spent. (default: 100000000pin - 1 ANATHA)

Treasury module

Description

The Treasury module is in charge of holding the initial supply of Anatha, generating the treasury public sale price based on the amount of Anatha transferred out of the treasury and receiving Anatha that had been bought back by the on-chain BuyBack functionality. The Treasury module will be controlled by an on-chain multi signature wallet with its threshold requirements specified in the genesis file. To fulfill the objectives from the Product document, this on-chain module requires a complementing off-chain module which is described in the Backend Services section. We can identify the following roles:

Manager - A maximum of 2 managers can exist. They have the ability to manage the list of Operators, cancel disbursements. Managers are set by governance
Operator - A keypair that has the possibility to distribute coins from the Treasury

Diagram

Transactions

Add operator

Add a new operator address. This transaction can only be invoked by treasury managers.

{

type: "treasury/AddOperator"

value: {

sender: AccAddress

operator: AccAddress

}

anathacli tx treasury operator add <operator_address> --from <address> [flags]

Remove operator

Remove an existing operator address. This transaction can only be invoked by treasury managers.

{

type: "treasury/RemoveOperator"

value: {

sender: AccAddress

operator: AccAddress

}

anathacli tx treasury operator remove <operator_address> --from <address> [flags]

Disburse tokens

Distribute an arbitrary amount of tokens to the recipient including a disbursement reference. High-value (risky) disbursements will be placed in the disbursement queue for a configurable time duration. This transaction can only be invoked by treasury operators.

{

type: "treasury/Disburse"

value: {

operator: AccAddress

recipient: AccAddress

amount: Coins

reference: string

}

anathacli tx treasury disburse <recipient> <amount> <reference> --from <address> [flags]

Cancel disbursement

Treasury managers can cancel high-value disbursements while they're still in the disbursement queue. Cancelled disbursements will not be executed and funds will not be distributed.

{

type: "treasury/CancelDisbursement"

value: {

manager: AccAddress

recipient: AccAddress

scheduled_for: string

}

anathacli tx treasury cancel-disbursement <recipient> <scheduled_for> --from <address> [flags]

Create sell order

Users can create a sell order if they wish to exchange their native tokens (pin) to the stable token (din). Exchange rate is based on the current price for the native token, and it is adjusted by the configurable buyback percentage parameter.

{

type: "treasury/CreateSellOrder"

value: {

seller: AccAddress

amount: Coins

}

anathacli tx treasury order sell <amount> --from <address> [flags]

Create buy order

Users can create a buy order if they wish to exchange their stable tokens (din) to the native token (pin). Exchange rate is based on the current price for the native token.

{

type: "treasury/CreateBuyOrder"

value: {

buyer: AccAddress

amount: Coins

}

anathacli tx treasury order buy <amount> --from <address> [flags]

Proposals

Transfer from distribution profits to buyback liquidity proposal

Create a new proposal to transfer stable tokens from distribution profits to the buyback liquidity fund.

{

type: "treasury/TransferFromDistributionProfitsToBuyBackLiquidityProposal"

value: {

title: string

description: string

amount: Coins

}

anathacli tx governance submit-proposal transfer-from-distribution-profits-to-buyback-liquidity <proposal_file.json> --from <address> [flags]

Add buyback liquidity proposal

Create a new proposal to add stable tokens to the buyback liquidity fund.

{

type: "treasury/AddBuyBackLiquidityProposal"

value: {

title: string

description: string

amount: Coins

}

anathacli tx governance submit-proposal add-buyback-liquidity <proposal_file.json> --from <address> [flags]

Remove buyback liquidity proposal

Create a new proposal to remove stable tokens from the buyback liquidity fund.

{

type: "treasury/RemoveBuyBackLiquidityProposal"

value: {

title: string

description: string

amount: Coins

}

anathacli tx governance submit-proposal remove-buyback-liquidity <proposal_file.json> --from <address> [flags]

Burn distribution profits proposal

Create a new proposal to burn stable tokens from the distribution profits fund.

{

type: "treasury/BurnDistributionProfitsProposal"

value: {

title: string

description: string

amount: Coins

}

anathacli tx governance submit-proposal burn-distribution-profits <proposal_file.json> --from <address> [flags]

Queries

Query Treasury parameters

Path: custom/treasury/parameters

anathacli query treasury params [flags]

Query current treasury state

Path: custom/treasury/treasury

anathacli query treasury treasury [flags]

Query treasury operators

Path: custom/treasury/operators

anathacli query treasury operators [flags]

Query current disbursement queue

Path: custom/treasury/disbursements

anathacli query treasury disbursements [flags]

Get current exchange price

Path: custom/treasury/price/:amount

anathacli query treasury price <amount> [flags]

Parameters

managers ([]sdk.AccAddress)

List of treasury managers.

risk_assesment_amount (sdk.Coins)

Disbursement with value higher than risk assessment amount will be placed in the disbursement queue. (default: 10000000000000din - 1000 usd)

risk_assesment_duration (time.Duration)

Time duration while risky disbursements stay in the disbursement queue. (default: 24 hours)

buyback_percentage (sdk.Dec)

Percentage of price when the system buys back tokens. (default: 0.24)

Distribution module

Description

This Distribution module implements a functional way to passively distribute rewards between network participants. For computation optimization, this mechanism does not distribute funds proactively, but rather allows the users to claim their rewards.

Diagram

Transactions

Withdraw name reward

Withdraw pending name rewards, which includes rewards currently in escrow. This transaction will fail if the reward withdrawal period hasn't passed, or if the sender doesn't have any pending name rewards.

{

type: "distribution/WithdrawNameReward"

value: {

sender: AccAddress

}

anathacli tx distribution withdraw-name-reward --from <address> [flags]

Withdraw validator reward

Withdraw pending validator rewards. This transaction will fail if the reward withdrawal period hasn't passed, or if the sender is not a validator operator.

{

type: "distribution/WithdrawValidatorReward"

value: {

validator: ValAddress

}

anathacli tx distribution withdraw-validator-reward --from <address> [flags]

Deposit savings

Deposit an arbitrary amount of tokens to the savings fund.

{

type: "distribution/DepositSavings"

value: {

sender: AccAddress

amount: Coins

}

anathacli tx distribution deposit-savings <amount> --from <address> [flags]

Withdraw savings

Withdraw savings and savings interest. If the reward withdrawal period hasn't passed, savings will be withdrawn, and interest will be moved to escrow until they can be withdrawn.

{

type: "distribution/WithdrawSavings"

value: {

sender: AccAddress

}

anathacli tx distribution withdraw-savings --from <address> [flags]

Withdraw savings interest

Withdraw pending savings interest, including tokens that are in escrow. This transaction will fail if the reward withdrawal hasn't passed, or if the sender is not a validator operator.

{

type: "distribution/WithdrawSavingsInterest"

value: {

sender: AccAddress

}

anathacli tx distribution withdraw-savings-interest --from <address> [flags]

Proposals

Distribute from development fund

This proposal allows governors to distribute funds from the development fund.

{

type: "distribution/DevelopmentFundDistributionProposal"

value: {

title: string

description: string

amount: Coins

recipient: AccAddress

}

anathacli tx governance submit-proposal development-fund-distribution <proposal_file.json> --from <address> [flags]

Distribute from security token fund

This proposal allows governors to distribute funds from the security token fund.

{

type: "distribution/SecurityTokenFundDistributionProposal"

value: {

title: string

description: string

recipients: [{

amount: Coins

recipient: AccAddress

}]

}

anathacli tx governance submit-proposal security-token-fund-distribution <proposal_file.json> --from <address> [flags]

Queries

Query Distribution parameters

Path: custom/distribution/parameters

anathacli query distribution params [flags]

Query pending name rewards

Path: custom/distribution/name-reward

anathacli query distribution name-reward <address> [flags]

Query pending validator rewards

Path: custom/distribution/validator-reward

anathacli query distribution validator-reward <vaL_address> [flags]

Query pending savings interest

Path: custom/distribution/savings-reward

anathacli query distribution savings-reward <address> [flags]

Query savings

Path: custom/distribution/savings

anathacli query distribution savings <address> [flags]

Parameters

name_deposit_delay (time.Duration)

Delay from when a name is registered to when it starts receiving rewards. (default: 24 hours)

reward_withdrawal_blocked_period (time.Duration)

Duration of the period while reward withdrawals are disabled. (default: 1 year)

reward_withdrawal_enabled_time (time.Time)

Timestamp after which reward withdrawals are enabled.

development_fund_share (sdk.Dec)

Share of tokens that goes to the development fund. (default: 0.25)

security_token_fund_share (sdk.Dec)

Share of tokens that goes to the security token fund. (default: 0.25)

savings_split_adjustment (sdk.Dec)

Percentage of the funds that go to savings accounts. (default: 0.9)

Fee module

Model

Application fees

Application fees are determined by the transaction value and they're calculated per transaction message. If the transaction doesn't involve token transfers or if it doesn't have a fixed fee, the application fee will be zero.

The following transaction messages have a non-zero application fee:

hra/Register

Message with a configurable fixed fee. (registration_fee)

hra/Renew

Message with a configurable fixed fee. (renewal_fee)

hra/Buy

Application fee is equal to the purchase amount.

hra/RegisterAddress

Message with a configurable fixed fee. (address_registration_fee)

The fee is only deducted if all address credits are spent. If they're not, the application fee is zero.

cosmos-sdk/MsgSend

Application fee is equal to the transfer amount.

cosmos-sdk/MsgMultiSend

Application fee is equal to the sum of all amounts in the inputs array.

treasury/CreateSellOrder

Application fee is equal to the amount of tokens that are being sold.

System fees

System fees are a small percentage of the determined transaction value, and they're calculated per transaction message. The percentage is a configurable parameter that can be changed through governance, and the default percentage is 0.2%.

Minimal system fee is also a configurable parameter, with a default value of 200pin.

If the message type is on the fee excluded messages list, the system fee will not be deducted.

For a valid transaction, the signer has to have enough funds to cover all application fees and system fees.

System fees will be deducted from signers for all transactions that pass basic validations (CheckTx) even if the transaction is marked as invalid in the DeliverTx phase.

Proposals

Add fee excluded message type

This proposal allows governors to add new message types to the fee excluded message types list.

{

type: "fee/AddFeeExcludedMessageProposal"

value: {

title: string

description: string

message_type: string

}

anathacli tx governance submit-proposal add-fee-excluded-message <proposal_file.json> --from <address> [flags]

Remove fee excluded message type

This proposal allows governors to remove message types from the fee excluded message types list.

{

type: "fee/RemoveFeeExcludedMessageProposal"

value: {

title: string

description: string

message_type: string

}

anathacli tx governance submit-proposal remove-fee-excluded-message <proposal_file.json> --from <address> [flags]

Queries

Query Fee parameters

Path: custom/fee/parameters

anathacli query fee params [flags]

Query fee excluded messages

Path: custom/fee/excluded-messages

anathacli query fee excluded-messages [flags]

Parameters

fee_percentage (sdk.Dec)

Transaction fee percentage. (default: 0.002)

minimum_fee (sdk.Coins)

Minimum fee per transaction message. (default: 200pin)

DevOps procedures

Makefile

Available make commands:

make install

Installs anatha core binaries to the $GOBIN directory.

make build

Builds anatha core binaries and places them in the build directory.

make build-linux

Build anatha core binaries for Linux platform. These binaries are used in Docker containers.

make go.sum

Checks if all anatha core dependencies are present and up to date.

make test

Runs tests.

make lint

Runs go linter utility and cleans up the code formatting.

make devnet-prepare

Executes all necessary commands for a clean devnet start. It clears previously stored blockchain data, imports all required account keys to the keystore and executes necessary steps to setup a validator.

make devnet-start

Starts the local one node network.

make build-docker

Builds the Docker image required for the multi-node local network.

make localnet-start

Starts the multi-node local network.

make localnet-stop

Stops the multi-node local network.

make clean

Removes previously built anatha core binaries.

make localnet

Executes all required steps to start a local multi-node network. (clean -> build-linux -> build-docker -> localnet-start)

make devnet

Executes all required steps to start a local one node network. (clean -> install -> devnet-prepare -> devnet-start)

make devnet-reset

Executes all required steps to reset a local one node network. (clean -> devnet-prepare -> devnet-start)

Go dependencies

Before executing other commands, you have to make sure that you have Go installed, and you have to install all required Go dependencies.

To install Go dependencies, use:

go mod tidy

Local deployment (one node network)

One node local network is the easiest way to test the network functionalities locally.

Before you proceed, please note that you'll need to have Go installed and set up on your machine. If you don't have it, install it first.

The simplest way to deploy a clean local one node network is to run the following command:

make devnet

This command will execute all necessary cleanup procedures and it will start the local network. It will also destroy all previous blockchain data and rebuild the necessary binaries.

If you just want to start the local one node network without the cleanup, you can run:

make devnet-start

This command will only start the local node process without any cleanup or rebuilding.

You can also manually reset the stored blockchain data by using:

make devnet-prepare

An you can rebuild the binaries manually with:

make install

Local deployment (multi-node network)

Local multi-node will run 4 concurrent blockchain validator nodes locally in Docker

Apart from having Go installed, to run the multi-node local network, you'll also have to have Docker and docker-compose installed.

The easiest way to start the local multi-node network is to run the following command:

make localnet

This command will execute all necessary steps, it'll rebuild the anatha binaries for Linux environment, it'll rebuild the Docker image and start the local multi-node network using docker-compose.

If you only want to restart the nodes without rebuilding the binaries and the Docker image, you can use:

make localnet-start

If you want more control over the process, you can run these steps manually.

make build-linux will rebuild the binaries for Linux environment

make build-docker will rebuild the docker images.

Remote deployment (multi-node, multi-region network)

Remote deployment scripts can run an arbitrary number of blockchain validator nodes in multiple AWS regions.

Before proceeding, please note that remote deployment scripts require that you have Ansible, Terraform and Python3 installed on your machine. If you don't have any one of those, please install them.

After you've installed dependencies, you have to make sure that all environmental variables are set correctly. Here's the list of variables that need to be set:

AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>"

AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>"

TESTNET_NAME="<TESTNET_NAME>"

CLUSTER_NAME="<CLUSTER_NAME>"

SSH_PRIVATE_FILE="$HOME/.ssh/<PRIVATE_KEY_FILE>"

SSH_PUBLIC_FILE="$HOME/.ssh/<PUBLIC_KEY_FILE>"

DAEMON_BINARY="$PWD/../build/anathad"

CLI_BINARY="$PWD/../build/anathacli"

MANAGER_BINARY="$PWD/../build/anathad-manager"

DD_API_KEY="<DD_API_KEY>"

DD_SITE="datadoghq.eu"

The last two variables are only required if you want to use DataDog logging/monitoring services.

The simplest way to execute a remote deployment is to use our new-testnet.sh script. It's located in the networks directory.

Usage:

./new-testnet.sh <testnet_name> <cluster_name> <number_of_regions> <nodes_per_region>

The script will rebuild the Linux anatha binaries if necessary, it will clean up data left from the previous deployment, it will set up the correct environment variables and it will run terraform and ansible scripts to complete the remote deployment.

Of course, since this process is essential, this script may not be sufficient. So, you have an option to execute every step manually, and have more control over the whole process.

Let's take a look at all available make commands for remote deployment:

make validators-start

First, it runs the terraform script to create required remote resources on AWS. After all machines are up and running, it'll execute ansible scripts to set up dependencies on remote machines and then it'll start all validator nodes.

make validators-stop

It'll destroy all remote AWS resources using terraform and therefore stop the whole testnet. Please note that this command is not reversible, it'll destroy all machines and delete all previously stored blockchain data.

make validators-status

Returns the current status of all running validator nodes.

make upgrade

Upload new binaries required for live upgrade procedure.

make list

Returns a list of all running machines on AWS.

make install-datadog

Install datadog agent for monitoring/logging.

make remove-datadog

Remove the datadog agent.

make extract-config

Extract configuration from all running validator nodes. This includes copying genesis.json and config.toml files from remote nodes.

Network upgrade procedure

Software upgrade proposal

Anatha blockchain supports live network upgrades which can be initiated by a governance proposal. So, to start a network upgrade procedure, first the software upgrade proposal has to go through governance and it has to be accepted.

To be compatible with the automated upgrade manager, the proposal has to follow a strict format. The upgrade manager will read the log messages from standard output to determine when an upgrade is needed. When an upgrade is needed the binary will print a line that matches this regular expression: UPGRADE "(.*)" NEEDED at height (\d+):(.*). The second match in the above regular expression can be a JSON object with a binaries key as described below. The name (first regexp) will be used to select the new binary to run. If it is present, the current subprocess will be killed, current will be upgraded to the new directory, and the new binary will be launched.

Take a look at the following proposal example:

{

type: "upgrade/SoftwareUpgradeProposal"

value: {

title: "Update network to genesis-3"

description: "Software upgrade proposal to upgrade the blockchain network to genesis-3 version."

plan: [{

name: "genesis-3"

height: 976000

info: '{

"binaries": { "linux/amd64":"https://<URL>/anatha.zip?checksum=sha256:<SHA256_CHECKSUM>"

}

}]

}

Structure of the Plan object is described in paragraphs below.

Adding upgrade handler

In order to execute an update correctly, you have to register an upgrade handler in upgraded binaries.

Add the following to app/app.go, after app.upgradeKeeper initialization (line 259):

app.upgradeKeeper.SetUpgradeHandler("<UPGRADE_NAME>", func(ctx sdk.Context, plan upgrade.Plan) {

// do whatever here

// this code will be invoked when the new binary is executed for the first time

})

Rebuilding binaries

You can rebuild the binaries by using:

make install

To place them in the $GOBIN directory.

make build

To place them in the build directory.

make build-linux

To build them for Linux and place them in the build directory.

Manual binary upload

The safest way to execute a live upgrade is to upload the new binaries to validators manually.

New binaries should be placed in:

~/.anathad/upgrade_manager/upgrades/<UPGRADE_NAME>/bin

To partly automate this process, you can use our upgrade ansible script. It will upload new binaries to correct directories to all validators that have been started by the remote deployment script.

Make sure that new binaries are in the build directory (built with make build-linux), and that UPGRADE_NAME environmental variable is set correctly. Then, you can run:

make upgrade

When the upgrade proposal is executed, the upgrade manager will restart the network with the new binary.

Automatic binary download

Generally, the system requires that the administrator place all relevant binaries on the disk before the upgrade happens. However, for people who don't need such control and want an easier setup , there is another option. If you set DAEMON_ALLOW_DOWNLOAD_BINARIES=on then when an upgrade is triggered and no local binary can be found, the upgrade manager will attempt to download and install the binary itself. The plan stored in the upgrade module has an info field for arbitrary json. This info is expected to be outputted on the halt log message. There are two valid format to specify a download in such a message:

First, you can store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the "binaries" key:

{

"binaries": { "linux/amd64":"https://<URL>/anatha.zip?checksum=sha256:<SHA256_CHECKSUM>"

}

Or, you can store a link to a file that contains all information in the above format (eg. if you want to specify lots of binaries, changelog info, etc without filling up the blockchain).

https://example.com/<UPGRADE_NAME>-info.json?checksum=sha256:<SHA256_CHECKSUM>

This file contained in the link will be retrieved by go-getter and the "binaries" field will be parsed as above.

If there is no local binary, DAEMON_ALLOW_DOWNLOAD_BINARIES=on, and we can access a canonical url for the new binary, then the upgrade_manager will download it with go-getter and unpack it into the upgrades/<UPGRADE_NAME> folder to be run as if we installed it manually

Note that for this mechanism to provide strong security guarantees, all URLs should include a sha{256,512} checksum. This ensures that no false binary is run, even if someone hacks the server or hijacks the dns. go-getter will always ensure the downloaded file matches the checksum if it is provided. And also handles unpacking archives into directories (so these download links should be a zip of all data in the bin directory).

To properly create a checksum on Linux/OSX, you can use the sha256sum utility:

sha256sum ./anatha-core/anatha.zip

You should get a result like this:

29139e1381b8177aec909fab9a75d11381cab5adf7d3af0c05ff1c9c117743a7

You can also use sha512sum if you like longer hashes. Make sure to set the hash algorithm properly in the checksum argument to the url.

Utility scripts

Prepare test

Path: scripts/prepare-test.sh

A script that prepares the blockchain for a fresh start. It will remove all previously stored blockchain data, it will reimport all important accounts that are used for local testing purposes, it will initialise a new genesis file with genesis transactions, and it will create one local validator that's used by the one node local network.

This script will be run when you execute make devnet or make devnet-prepare.

Redeploy testnet

Path: scripts/redeploy_testnet.sh

A script that contains all necessary commands used to redeploy a remote one node network and upgrade it to a new version. Please note that this script will also remove all previously stored blockchain data by executing the prepare-test script described above, it'll pull changes from Git, it'll rebuild the binaries and restart the system service.

Testing

Via SDK

The easiest way to test if all transactions and queries are working as expected is to run system tests available in the SDK. These tests will execute transactions with arbitrary test data and check if the application logic is working correctly.

Before proceeding, make sure that the local network is running in the background. You can also execute tests on a remote network by changing the nodeUrl appropriately (line 6 in test/test.js).

To do this, navigate to the anatha-sdk directory and run:

npm run test

That's it. All tests should pass if everything is working correctly.

Via CLI scenarios

While developing the blockchain, we've developed a lot of testing scenario scripts for all modules that we've worked on. You can use these scenarios for testing purposes.

CLI scenarios can be found in the test directory, in the root of the project. Currently, these are the available scenarios: