Heimdall

Heimdall is the heart of the Ramestta network. It manages validators, block producer selection, spans, the state-sync mechanism between Polygon and Ramestta, and other essential aspects of the system. It uses the Cosmos-SDK and a forked version of Tendermint, called Peppermint. Heimdall removes some of the modules from Cosmos-SDK but mostly uses a customized version of it while following the same pattern.

Heimdall and Bor

Heimdall’s bor module is responsible for managing span intervals and coordinating interactions with the Bor chain. Specifically, it determines when a new span can be proposed on Heimdall based on the current block number n and the current span span. A new span proposal is permissible when the current Bor chain block number n falls within the range of span.StartBlock and span.EndBlock (inclusive of StartBlock and exclusive of EndBlock). Validators on the Heimdall chain can propose a new span when these conditions are met.

Messages

MsgProposeSpan

The MsgProposeSpan message plays a crucial role in setting up the validator committee for a specific span and records a new span in the Heimdall state. This message is detailed in the Heimdall source code at bor/handler.go#L27.

// MsgProposeSpan creates msg propose span
type MsgProposeSpan struct {
 ID         uint64                  `json:"span_id"`
 Proposer   hmTypes.HeimdallAddress `json:"proposer"`
 StartBlock uint64                  `json:"start_block"`
 EndBlock   uint64                  `json:"end_block"`
 ChainID    string                  `json:"bor_chain_id"`
}

Selection of Producers

The process for choosing producers from among all validators involves a two-step mechanism:

1. Slot Allocation Based on Validator Power: Each validator is assigned a number of slots proportional to their power. For instance, a validator with a power rating of 10 will receive 10 slots, while one with a power rating of 20 will receive 20 slots. This method ensures that validators with higher power have a correspondingly higher chance of being selected.

2. Shuffling and Selection: All allocated slots are then shuffled using a seed derived from the Polygon (MATIC 1.0) block hash corresponding to each span n. The first producerCount producers are selected from this shuffled list. The bor module on Heimdall employs the Polygon 2.0 shuffle algorithm for this selection process. The algorithm’s implementation can be viewed at bor/selection.go.

This method of selection ensures that the process is both fair and weighted according to the validators’ power, thereby maintaining a balanced and proportional representation in the span committee.

// SelectNextProducers selects producers for the next span by converting power to slots
// spanEligibleVals - all validators eligible for next span
func SelectNextProducers(blkHash common.Hash, spanEligibleVals []hmTypes.Validator, producerCount uint64) (selectedIDs []uint64, err error) {
 if len(spanEligibleVals) <= int(producerCount) {
  for _, val := range spanEligibleVals {
   selectedIDs = append(selectedIDs, uint64(val.ID))
  }
  return
 }

 // extract seed from hash
 seed := helper.ToBytes32(blkHash.Bytes()[:32])
 validatorIndices := convertToSlots(spanEligibleVals)
 selectedIDs, err = ShuffleList(validatorIndices, seed)
 if err != nil {
  return
 }
 return selectedIDs[:producerCount], nil
}

// converts validator power to slots
func convertToSlots(vals []hmTypes.Validator) (validatorIndices []uint64) {
 for _, val := range vals {
  for val.VotingPower >= types.SlotCost {
   validatorIndices = append(validatorIndices, uint64(val.ID))
   val.VotingPower = val.VotingPower - types.SlotCost
  }
 }
 return validatorIndices
}

Types

Here are the span details that Heimdall uses:

// Span structure
type Span struct {
 ID                uint64       `json:"span_id" yaml:"span_id"`
 StartBlock        uint64       `json:"start_block" yaml:"start_block"`
 EndBlock          uint64       `json:"end_block" yaml:"end_block"`
 ValidatorSet      ValidatorSet `json:"validator_set" yaml:"validator_set"`
 SelectedProducers []Validator  `json:"selected_producers" yaml:"selected_producers"`
 ChainID           string       `json:"bor_chain_id" yaml:"bor_chain_id"`
}

Parameters

The Bor module contains the following parameters:

Key

Type

Default value

Duration (*)

SprintDuration.

uint64

16 blocks

32 seconds

SpanDuration

uint64

100 * SprintDuration = 1,600 blocks

3,200 seconds (53min and 20s)

ProducerCount

uint64

4 blocks

8 seconds

(*): Given that blocks are produced every 2 seconds on Bor.

CLI Commands

Span propose tx

heimdallcli tx bor propose-span \
 --start-block <start-block> \
 --chain-id <heimdall-chain-id>

Query current span

heimdallcli query bor span latest-span --chain-id <heimdall-chain-id>

Expected output:

{
  "span_id":2,
  "start_block":6656,
  "end_block":13055,
  "validator_set":{
    "validators":[
      {
        "ID":1,
        "startEpoch":0,
        "endEpoch":0,
        "power":1,
        "pubKey":"0x04b12d8b2f6e3d45a7ace12c4b2158f79b95e4c28ebe5ad54c439be9431d7fc9dc1164210bf6a5c3b8523528b931e772c86a307e8cff4b725e6b4a77d21417bf19",
        "signer":"0x6c468cf8c9879006e22ec4029696e005c2319c9d",
        "last_updated":"",
        "accum":0
      }
    ],
    "proposer":{
      "ID":1,
      "startEpoch":0,
      "endEpoch":0,
      "power":1,
      "pubKey":"0x04b12d8b2f6e3d45a7ace12c4b2158f79b95e4c28ebe5ad54c439be9431d7fc9dc1164210bf6a5c3b8523528b931e772c86a307e8cff4b725e6b4a77d21417bf19",
      "signer":"0x6c468cf8c9879006e22ec4029696e005c2319c9d",
      "last_updated":"",
      "accum":0
    }
  },
  "selected_producers":[
    {
      "ID":1,
      "startEpoch":0,
      "endEpoch":0,
      "power":1,
      "pubKey":"0x04b12d8b2f6e3d45a7ace12c4b2158f79b95e4c28ebe5ad54c439be9431d7fc9dc1164210bf6a5c3b8523528b931e772c86a307e8cff4b725e6b4a77d21417bf19",
      "signer":"0x6c468cf8c9879006e22ec4029696e005c2319c9d",
      "last_updated":"",
      "accum":0
    }
  ],
  "bor_chain_id":"1370"
}

Query span by id

heimdallcli query bor span --span-id <span-id> --chain-id <heimdall-chain-id>

It prints the result in same format as above.

Parameters

To print all params;

heimdalldcli query bor params

Expected Result:

sprint_duration: 16
span_duration: 1600
producer_count: 4

REST APIs

Name

Method

Endpoint

Span details

GET

/bor/span/span-id

Get latest span

GET

/bor/latest-span

Get params

GET

/bor/params

Authentication

Heimdall’s 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.

Gas and fees

Fees serve two purposes for an operator of the network.

Fees limit the growth of the state stored by every full node and allow for general purpose censorship of transactions of little economic value. Fees are best suited as an anti-spam mechanism where validators are disinterested in the use of the network and identities of users.

Since Heimdall doesn’t support custom contract or code for any transaction, it uses fixed cost transactions. For fixed cost transactions, the validator can top up their accounts on the Ethereum chain and get tokens on Heimdall using the Topup module.

Types

Besides accounts (specified in State), the types exposed by the auth module are StdSignature, the combination of an optional public key and a cryptographic signature as a byte array, StdTx, a struct that implements the sdk.Tx interface using StdSignature, and StdSignDoc, a replay-prevention structure for StdTx which transaction senders must sign over.

StdSignature

A StdSignature is the types of a byte array.

// StdSignature represents a sig
type StdSignature []byte

StdTx

A StdTx is a struct that implements the sdk.Tx interface, and is likely to be generic enough to serve the purposes of many types of transactions.

type StdTx struct {
  Msg       sdk.Msg      `json:"msg" yaml:"msg"`
  Signature StdSignature `json:"signature" yaml:"signature"`
  Memo      string       `json:"memo" yaml:"memo"`
}

StdSignDoc

A StdSignDoc is a replay-prevention structure to be signed over, which ensures that any submitted transaction (which is simply a signature over a particular byte string) will only be executable once on a Heimdall.

// StdSignDoc is replay-prevention structure.
// It includes the result of msg.GetSignBytes(),
// as well as the ChainID (prevent cross chain replay)
// and the Sequence numbers for each signature (prevent
// inchain replay and enforce tx ordering per account).
type StdSignDoc struct {
 ChainID       string          `json:"chain_id" yaml:"chain_id"`
 AccountNumber uint64          `json:"account_number" yaml:"account_number"`
 Sequence      uint64          `json:"sequence" yaml:"sequence"`
 Msg           json.RawMessage `json:"msg" yaml:"msg"`
 Memo          string          `json:"memo" yaml:"memo"`
}

Account

It manages addresses, coins and nonce for transactions. It also signs and validates transactions.

type BaseAccount struct {
  Address types.HeimdallAddress `json:"address" yaml:"address"`
  Coins types.Coins `json:"coins" yaml:"coins"`
  PubKey crypto.PubKey `json:"public_key" yaml:"public_key"`
  AccountNumber uint64 `json:"account_number" yaml:"account_number"`
  Sequence uint64 `json:"sequence" yaml:"sequence"`
}

Parameters

The auth module contains the following parameters:

Key

Type

Default value

MaxMemoCharacters

uint64

256

TxSigLimit

uint64

TxSizeCostPerByte

uint64

SigVerifyCostED25519

uint64

590

SigVerifyCostSecp256k1

uint64

1000

DefaultMaxTxGas

uint64

1000000

DefaultTxFees

string

“1000000000000000”

CLI commands

Show account

To print account related data into Heimdall;

heimdalld show-account

Expected Result:

{
 "address": "0x68243159a498cf20d945cf3E4250918278BA538E",
 "pub_key": "0x040a9f6879c7cdab7ecc67e157cda15e8b2ddbde107a04bc22d02f50032e393f6360a05e85c7c1ecd201ad30dfb886af12dd02b47e4463f6f0f6f94159dc9f10b8"
}

Account and coin details

To display account details, coins, sequence and account number;

heimdallcli query auth account 0x68243159a498cf20d945cf3E4250918278BA538E --trust-node

Expected Result:

address: 0x68243159a498cf20d945cf3e4250918278ba538e
coins:
- denom: RAMA
    amount:
    i: "1000000000000000000000"
pubkey: ""
accountnumber: 0
sequence: 0

Parameters

To print all params;

heimdallcli query auth params

Expected Result:

max_memo_characters: 256
tx_sig_limit: 7
tx_size_cost_per_byte: 10
sig_verify_cost_ed25519: 590
sig_verify_cost_secp256k1: 1000
max_tx_gas: 1000000
tx_fees: "1000000000000000"

REST APIs

Name

Endpoint

Description

Account details

/auth/accounts/{address}

Returns all details for an address

Account sequence details

/auth/accounts/{address}/sequence

Returns only necessary details for signing

Auth params

/auth/params

Returns all params auth module uses

Key management

Each validator uses two keys to manage validator related activities on Ramestta. The Signer key is kept on the node and is generally considered a hot wallet, whereas the Owner key is supposed to kept very secure, is used infrequently, and is generally considered a cold wallet. The staked funds are controlled by the Owner key.

This separation of responsibilities has been done to ensure an efficient tradeoff between security and ease of use. Both keys are Polygon compatible addresses and work exactly the same manner. And yes, it is possible to have same Owner and Signer keys.

Signer key

The signer key is an address that is used for signing Heimdall blocks, checkpoints, and other signing related activities. This key’s private key will be on the Validator node for signing purposes. It cannot manage stake, rewards or delegations.

The validator must keep two types of balances on this address:

Rama tokens on Heimdall (through Topup transactions) to perform validator responsibilities on Heimdall
MATIC on Polygon chain to send checkpoints on Polygon

Owner key

The owner key is an address that is used for staking, re-stake, changing the signer key, withdraw rewards and manage delegation related parameters on the Polygon chain. The private key for this key must be secure at all cost.

All transactions through this key will be performed on the Polygon chain.

Signer change

Following event is generated in case of signer change on Polygon chain on StakingInfo.sol:

// Signer change
event SignerChange(
  uint256 indexed validatorId,
  address indexed oldSigner,
  address indexed newSigner,
  bytes signerPubkey
);

Heimdall bridge processes these events and sends transactions on Heimdall to change state based on the events.

Validation

Heimdall’s “Ante Handler” plays a crucial role in the integrity and efficiency of transaction processing. It is primarily responsible for the preliminary verification and validation of all transactions, ensuring that they meet the necessary criteria before being included in a block. This includes checking the sender’s balance to ensure there are sufficient funds to cover transaction fees and subsequently deducting these fees for successful transactions.

Advanced Gas Management in Heimdall

Block and Transaction Gas Limits

Heimdall employs a gas limit system to regulate the computational and storage resources consumed by transactions and blocks. This system is designed to prevent excessive block sizes and ensure network stability.

Block Gas Limit

Each block in Heimdall has a maximum gas limit, constraining the total gas used by all transactions within the block. The sum of the gas used by each transaction in a block must not exceed this limit:

 block.GasLimit >= sum(tx1.GasUsed + tx2.GasUsed + ..... + txN.GasUsed)

The maximum block gas limit and block size are specified as part of the consensus parameters during the application setup, as seen in the Heimdall source code at app.go#L464-L471:

maxGasPerBlock   int64 = 10000000 // 10 Million
maxBytesPerBlock int64 = 22020096 // 21 MB

// Setting consensus parameters
ConsensusParams: &abci.ConsensusParams{
 Block: &abci.BlockParams{
  MaxBytes: maxBytesPerBlock,
  MaxGas:   maxGasPerBlock,
 },
 ...
},

Transaction Gas Limit

For individual transactions, the gas limit is determined by parameters in the auth module and can be modified through Heimdall’s governance (gov) module.

Special Handling of Checkpoint Transactions

Checkpoint transactions, which require Merkle proof verification on the Polygon chain, are treated distinctly. To streamline processing and avoid the overhead of additional Merkle proof verification, Heimdall restricts blocks containing a MsgCheckpoint transaction to just that one transaction:

// Gas requirement for checkpoint transaction
gasWantedPerCheckpoinTx sdk.Gas = 10000000 // 10 Million

// Special gas limit handling for checkpoint transactions
if stdTx.Msg.Type() == "checkpoint" && stdTx.Msg.Route() == "checkpoint" {
 gasForTx = gasWantedPerCheckpoinTx
}

Enhanced Transaction Verification and Replay Protection

The Ante Handler in Heimdall is instrumental in ensuring the legitimacy and uniqueness of transactions. It performs a thorough verification of incoming transactions, including signature validation, as delineated in the source code at ante.go#L230-L266.

Sequence Number for Replay Protection

A critical aspect of transaction security in Heimdall is the use of a sequenceNumber in each transaction. This feature is a safeguard against replay attacks, where a transaction might be fraudulently or mistakenly repeated. To prevent such scenarios, the Ante Handler increments the sequence number for the sender’s account after each successful transaction. This incrementation ensures that each transaction is unique and that previous transactions cannot be replayed.

In summary, Heimdall’s Ante Handler, along with its sophisticated gas management and transaction verification systems, provides a robust framework for secure and efficient transaction processing. The careful balance of block and transaction gas limits, coupled with advanced replay protection mechanisms, ensures the smooth operation of the Heimdall chain within the Ramestta network.

Balance transfers

Heimdall’s bank module handles balance transfers between accounts. This module corresponds to the bank module from cosmos-sdk.

Messages

MsgSend

MsgSend handles transfer between accounts in Heimdall. Here is a structure for transaction message:

// MsgSend - high-level transaction of the coin module
type MsgSend struct {
 FromAddress types.HeimdallAddress `json:"from_address"`
 ToAddress   types.HeimdallAddress `json:"to_address"`
 Amount      types.Coins           `json:"amount"`
}

MsgMultiSend

MsgMultiSend handles multi transfer between account for Heimdall.

// MsgMultiSend - high-level transaction of the coin module
type MsgMultiSend struct {
 Inputs  []Input  `json:"inputs"`
 Outputs []Output `json:"outputs"`
}

Parameters

The bank module contains the following parameters:

Key

Type

Default value

sendenabled

bool

true

CLI Commands

Send Balance

Following command will send 1000 Rama tokens to mentioned address;

heimdallcli tx bank send <address> 1000rama --chain-id <chain-id>

Staking

Staking module manages validator related transactions and state for Heimdall. Note that a validator stakes their tokens on the Polygon chain and becomes a validator. Respective validators send the transactions on Heimdall using necessary parameters to acknowledge the Polygon stake change. Once the majority of the validators agree on the change on the stake, this module saves the validator information on Heimdall state.

Messages

MsgValidatorJoin

MsgValidatorJoin handles the staking when a new validator joins the system. Once validator calls stake or stakeFor in StakingManager.sol on Polygon, and the new Staked event is emitted.

Source:

/**
 * Staked event - emitted whenever new validator 
 * 
 * @param signer           Signer address for the validator
 * @param validatorId      Validator id
 * @param activationEpoch  Activation epoch for validator
 * @param amount           Staked amount
 * @param total            Total stake
 * @param signerPubKey     Signer public key (required by Heimdall/Tendermint)
 */
event Staked(
    address indexed signer,
    uint256 indexed validatorId,
    uint256 indexed activationEpoch,
    uint256 amount,
    uint256 total,
    bytes signerPubkey
);

activationEpoch is the checkpoint count from where a validator will become active on Heimdall.

Stake call on smart contract fails if slots are unavailable. Validator slots are the way to restrict a number of validators in the system. Slots are managed on Polygon smart contracts.

Here is ValidatorJoin message for Heimdall transaction:

type MsgValidatorJoin struct {
 From         hmTypes.HeimdallAddress `json:"from"`
 ID           hmTypes.ValidatorID     `json:"id"`
 SignerPubKey hmTypes.PubKey          `json:"pub_key"`
 TxHash       hmTypes.HeimdallHash    `json:"tx_hash"`
 LogIndex     uint64                  `json:"log_index"`
}

MsgStakeUpdate

MsgStakeUpdate handles the stake update when a validator the re-stakes or new delegation comes in. In either case, the new StakeUpdate event is emitted.

/**
 * Stake update event - emitted whenever stake gets updated 
 * 
 * @param validatorId      Validator id
 * @param newAmount        New staked amount
 */
event StakeUpdate(
 uint256 indexed validatorId, 
 uint256 indexed newAmount
);

Here is MsgStakeUpdate message for Heimdall transaction:

// MsgStakeUpdate represents stake update
type MsgStakeUpdate struct {
 From     hmTypes.HeimdallAddress `json:"from"`
 ID       hmTypes.ValidatorID     `json:"id"`
 TxHash   hmTypes.HeimdallHash    `json:"tx_hash"`
 LogIndex uint64                  `json:"log_index"`
}

MsgValidatorExit

MsgValidatorExit handles the validator exit process after a validator initiates the exit process on Ethereum. It emits SignerUpdate event.

/**
 * Unstake init event - emitted whenever validator initiates the exit
 * 
 * @param user                Signer
 * @param validatorId         Validator id
 * @param deactivationEpoch   Deactivation epoch for validator
 * @param amount              Unstaked amount
 */
event UnstakeInit(
    address indexed user,
    uint256 indexed validatorId,
    uint256 deactivationEpoch,
    uint256 indexed amount
);

Here is MsgValidatorExit message for Heimdall transaction:

type MsgValidatorExit struct {
 From     hmTypes.HeimdallAddress `json:"from"`
 ID       hmTypes.ValidatorID     `json:"id"`
 TxHash   hmTypes.HeimdallHash    `json:"tx_hash"`
 LogIndex uint64                  `json:"log_index"`
}

MsgSignerUpdate

MsgSignerUpdate handles the signer update when a validator updates signer key on Ethereum. It emits SignerUpdate event.

/**
 * Signer change event - emitted whenever signer key changes
 * 
 * @param validatorId      Validator id
 * @param oldSigner        Current old signer
 * @param newSigner        New signer
 * @param signerPubkey     New signer public key
 */
event SignerChange(
    uint256 indexed validatorId,
    address indexed oldSigner,
    address indexed newSigner,
    bytes signerPubkey
);

Here is MsgSignerUpdate message for Heimdall transaction:

// MsgSignerUpdate signer update struct
type MsgSignerUpdate struct {
 From            hmTypes.HeimdallAddress `json:"from"`
 ID              hmTypes.ValidatorID     `json:"id"`
 NewSignerPubKey hmTypes.PubKey          `json:"pubKey"`
 TxHash          hmTypes.HeimdallHash    `json:"tx_hash"`
 LogIndex        uint64                  `json:"log_index"`
}

CLI Commands

Validator details

By signer address

heimdallcli query staking validator-info \
 --validator=<signer-address> \
 --chain-id <chain-id>

This command should display the following output:

{
    "ID":1,
    "startEpoch":0,
    "endEpoch":0,
    "power":10,
    "pubKey":"0x04b12d8b2f6e3d45a7ace12c4b2158f79b95e4c28ebe5ad54c439be9431d7fc9dc1164210bf6a5c3b8523528b931e772c86a307e8cff4b725e6b4a77d21417bf19",
    "signer":"0x6c468cf8c9879006e22ec4029696e005c2319c9d",
    "last_updated":0,
    "accum":0
}

By validator address

heimdallcli query staking validator-info \
 --id=<validator-id> \
 --chain-id=<chain-id>

This command should display the following output:

{
    "ID":1,
    "startEpoch":0,
    "endEpoch":0,
    "power":10,
    "pubKey":"0x04b12d8b2f6e3d45a7ace12c4b2158f79b95e4c28ebe5ad54c439be9431d7fc9dc1164210bf6a5c3b8523528b931e772c86a307e8cff4b725e6b4a77d21417bf19",
    "signer":"0x6c468cf8c9879006e22ec4029696e005c2319c9d",
    "last_updated":0,
    "accum":0
}

Validator join

This command sends validator join command through CLI:

heimdallcli tx staking validator-join \
 --signer-pubkey <signer-public-key> \
 --tx-hash <tx-hash>   \
 --log-index <log-index> \ 
 --chain-id <chain-id>

tx-hash value must be the same as Ethereum TX hash which emitted Staked event and log-index must be the same at which index the event is emitted.

REST APIs

Name

Method

Endpoint

Get Heimdall validator set

GET

/staking/validator-set

Get validator details

GET

/staking/validator/validator-id

All query APIs will result in following format:

{
 "height": "1",
 "result": {
  ...   
 }
}

Checkpoints

Checkpoints are vital components of the Ramestta network, representing snapshots of the Bor chain state. These checkpoints are attested by a majority of the validator set before being validated and submitted on Polygon contracts.

Heimdall, an integral part of this process, manages checkpoint functionalities using the checkpoint module. It coordinates with the Bor chain to verify checkpoint root hashes when a new checkpoint is proposed.

Checkpoint life-cycle and types

Life-cycle

Heimdall selects the next proposer using Tendermint’s leader selection algorithm. The multi-stage checkpoint process is crucial due to potential failures when submitting checkpoints on the Polygon chain caused by factors like gas limit, network traffic, or high gas fees.

Each checkpoint has a validator as the proposer. The outcome of a checkpoint on the Polygon chain (success or failure) triggers an ack (acknowledgment) or no-ack (no acknowledgment) transaction, altering the proposer for the next checkpoint on Heimdall.

Types and structures

Checkpoint block header

type CheckpointBlockHeader struct {
 Proposer        types.HeimdallAddress `json:"proposer"`
 StartBlock      uint64                `json:"startBlock"`
 EndBlock        uint64                `json:"endBlock"`
 RootHash        types.HeimdallHash    `json:"rootHash"`
 AccountRootHash types.HeimdallHash    `json:"accountRootHash"`
 TimeStamp       uint64                `json:"timestamp"`
}

Root hash calculation

The RootHash is calculated as a Merkle hash of Bor block hashes from StartBlock to EndBlock. The process involves hashing each block’s number, time, transaction hash, and receipt hash, then creating a Merkle root of these hashes.

blockHash = keccak256([number, time, tx hash, receipt hash])

Pseudocode for the root hash for 1 to n Bor blocks:

B(1) := keccak256([number, time, tx hash, receipt hash])
B(2) := keccak256([number, time, tx hash, receipt hash])
.
.
.
B(n) := keccak256([number, time, tx hash, receipt hash])

// checkpoint is Merkle root of all block hash
checkpoint's root hash = Merkel[B(1), B(2), ....., B(n)]

Here are some snippets of how checkpoint is created from Bor chain block headers.

Source:

// Golang representation of block data used in checkpoint
blockData := crypto.Keccak256(appendBytes32(
 blockHeader.Number.Bytes(),
 new(big.Int).SetUint64(blockHeader.Time).Bytes(),
 blockHeader.TxHash.Bytes(),
 blockHeader.ReceiptHash.Bytes(),
))

// array of block hashes of Bor blocks
headers := [blockData1, blockData2, ..., blockDataN]

// merkel tree
tree := merkle.NewTreeWithOpts(merkle.TreeOptions{EnableHashSorting: false, DisableHashLeaves: true})
tree.Generate(convert(headers), sha3.NewLegacyKeccak256())

// create checkpoint's root hash
rootHash := tree.Root().Hash

AccountRootHash

AccountRootHash is the hash of the validator account-related information that needs to pass to the Polygon chain at each checkpoint.

eachAccountHash := keccak256([validator id, withdraw fee, slash amount])

Pseudocode for the account root hash for 1 to n Bor blocks:

B(1) := keccak256([validator id, withdraw fee, slash amount])
B(2) := keccak256([validator id, withdraw fee, slash amount])
.
.
.
B(n) := keccak256([validator id, withdraw fee, slash amount])

// account root hash is Merkle root of all block hash
checkpoint's account root hash = Merkel[B(1), B(2), ....., B(n)]

Golang code for the account hash can be found here:

// DividendAccount contains Fee, Slashed amount
type DividendAccount struct {
 ID            DividendAccountID `json:"ID"`
 FeeAmount     string            `json:"feeAmount"`     // string representation of big.Int
 SlashedAmount string            `json:"slashedAmount"` // string representation of big.Int
}

// calculate hash for particular account
func (da DividendAccount) CalculateHash() ([]byte, error) {
 fee, _ := big.NewInt(0).SetString(da.FeeAmount, 10)
 slashAmount, _ := big.NewInt(0).SetString(da.SlashedAmount, 10)
 divAccountHash := crypto.Keccak256(appendBytes32(
  new(big.Int).SetUint64(uint64(da.ID)).Bytes(),
  fee.Bytes(),
  slashAmount.Bytes(),
 ))

 return divAccountHash, nil
}

Messages in checkpoint module

MsgCheckpoint

MsgCheckpoint handles checkpoint verification on Heimdall, utilizing RLP encoding for Polygon chain verification. It prioritizes transactions with high gas consumption to ensure only one MsgCheckpoint transaction per block.

// MsgCheckpoint represents checkpoint transaction
type MsgCheckpoint struct {
 Proposer        types.HeimdallAddress `json:"proposer"`
 StartBlock      uint64                `json:"startBlock"`
 EndBlock        uint64                `json:"endBlock"`
 RootHash        types.HeimdallHash    `json:"rootHash"`
 AccountRootHash types.HeimdallHash    `json:"accountRootHash"`
}

MsgCheckpointAck

MsgCheckpointAck manages successful checkpoint submissions, updating the checkpoint count and clearing the checkpointBuffer.

// MsgCheckpointAck represents checkpoint ack transaction if checkpoint is successful
type MsgCheckpointAck struct {
 From        types.HeimdallAddress `json:"from"`
 HeaderBlock uint64                `json:"headerBlock"`
 TxHash      types.HeimdallHash    `json:"tx_hash"`
 LogIndex    uint64                `json:"log_index"`
}

MsgCheckpointNoAck

MsgCheckpointNoAck deals with unsuccessful checkpoints or offline proposers, allowing a timeout period before selecting a new proposer.

// MsgCheckpointNoAck represents checkpoint no-ack transaction
type MsgCheckpointNoAck struct {
 From types.HeimdallAddress `json:"from"`
}

Parameters and CLI commands

Parameters

The checkpoint module contains the following parameters:

Key

Type

Default value

CheckpointBufferTime

uint64

1000 * time.Second

CLI commands

Commands are available for various actions such as sending checkpoints, sending ack or no-ack transactions, and querying parameters.

Printing all parameters

heimdallcli query checkpoint params --trust-node

Expected Result:

checkpoint_buffer_time: 16m40s

Send Checkpoint

Following command sends checkpoint transaction on Heimdall:

heimdallcli tx checkpoint send-checkpoint \
 --start-block=<start-block> \
 --end-block=<end-block> \
 --root-hash=<root-hash> \
 --account-root-hash=<account-root-hash> \
 --chain-id=<chain-id>

Send `ack`

Following command sends ack transaction on Heimdall if checkpoint is successful on Polygon:

heimdallcli tx checkpoint send-ack \
 --tx-hash=<checkpoint-tx-hash>
 --log-index=<checkpoint-event-log-index>
 --header=<checkpoint-index> \
  --chain-id=<chain-id>

Send `no-ack`

Following command send no-ack transaction on Heimdall:

heimdallcli tx checkpoint send-noack --chain-id <chain-id>

REST APIs

Heimdall provides several REST APIs for interacting with the checkpoint module, including endpoints for preparing messages, querying checkpoints, and more.

Name

Method

Endpoint

It returns the prepared msg for ack checkpoint

POST

/checkpoint/ack

It returns the prepared msg for new checkpoint

POST

/checkpoint/new

It returns the prepared msg for no-ack checkpoint

POST

/checkpoint/no-ack

Checkpoint by number

GET

/checkpoints/<checkpoint-number>

Get current checkpoint buffer state

GET

/checkpoints/buffer

Get checkpoint counts

GET

/checkpoints/count

Get last no-ack details

GET

/checkpoints/last-no-ack

Get latest checkpoint

GET

/checkpoints/latest

All checkpoints

GET

/checkpoints/list

It returns the checkpoint parameters

GET

/checkpoints/parama

It returns the prepared checkpoint

GET

/checkpoints/prepare

Get ack count, buffer, validator set, validator count and last-no-ack details

GET

/overview

For more details and the response format of these APIs, visit Heimdall API Documentation.

Topup

Topups are amounts used to pay fees on the Heimdall chain.

There are two ways to topup your account:

When new validator joins, they can mention a topup amount as top-up in addition to the staked amount, which will be moved as balance on Heimdall chain to pays fees on Heimdall.
A user can directly call the top-up function on the staking smart contract on Polygon to increase top-up balance on Heimdall.

Messages

MsgTopup

MsgTopup transaction is responsible for minting balance to an address on Heimdall based on Polygon chain’s TopUpEvent on staking manager contract.

Handler for this transaction processes top-up and increases the balance only once for any given msg.TxHash and msg.LogIndex. It throws Older invalid tx found error, if trying to process the top-up more than once.

Here is the structure for the top-up transaction message:

type MsgTopup struct {
 FromAddress types.HeimdallAddress `json:"from_address"`
 ID          types.ValidatorID     `json:"id"`
 TxHash      types.HeimdallHash    `json:"tx_hash"`
 LogIndex    uint64                `json:"log_index"`
}

MsgWithdrawFee

MsgWithdrawFee transaction is responsible for withdrawing balance from Heimdall to Polygon chain. A Validator can withdraw any amount from Heimdall.

Handler processes the withdraw by deducting the balance from the given validator and prepares the state to send the next checkpoint. The next possible checkpoint will contain the withdraw related state for the specific validator.

Handler gets validator information based on ValidatorAddress and processes the withdraw.

// MsgWithdrawFee - high-level transaction of the fee coin withdrawal module
type MsgWithdrawFee struct {
 ValidatorAddress types.HeimdallAddress `json:"from_address"`
 Amount           types.Int             `json:"amount"`
}

CLI Commands

Topup fee

heimdallcli tx topup fee
 --log-index <log-index> 
 --tx-hash <transaction-hash> 
 --validator-id <validator ID here>
 --chain-id <heimdall-chain-id>

Withdraw fee

heimdallcli tx topup withdraw --chain-id <heimdall-chain-id>

To check reflected topup on account run following command

heimdallcli query auth account <validator-address> --trust-node

REST APIs

Name

Method

URL

Body Params

Topup Fee

POST

/topup/fee

id Validator id, tx_hash Transaction hash of successful topup event on Polygon chain, log_index Log index of topup event emitted on Polygon chain

Withdraw Fee

POST

/topup/withdraw

amount Withdraw amount

Chain management

This document specifies an overview of the chain manager module of Heimdall.

The chain manager module provides all necessary dependencies like contract-addresses, bor_chain_id, and tx_confirmation_time. Other parameters can be added to this later on.

Params are updated through the gov module.

Types

Chainmanager structure on Heimdall looks like the following:

type ChainParams struct {
 // BorChainID is valid bor chainId
 BorChainID            string                  `json:"bor_chain_id" yaml:"bor_chain_id"`

 // StakingManagerAddress is valid contract address
 StakingManagerAddress hmTypes.HeimdallAddress `json:"staking_manager_address" yaml:"staking_manager_address"`

 // RootChainAddress is valid contract address
 RootChainAddress      hmTypes.HeimdallAddress `json:"root_chain_address" yaml:"root_chain_address"`

 // StakingInfoAddress is valid contract address
 StakingInfoAddress    hmTypes.HeimdallAddress `json:"staking_info_address" yaml:"staking_info_address"`

 // StateSendedAddress is valid contract address
 StateSenderAddress    hmTypes.HeimdallAddress `json:"state_sender_address" yaml:"state_sender_address"`

 // Bor Chain Contracts
 // StateReceiveAddress is valid contract address
 StateReceiverAddress hmTypes.HeimdallAddress `json:"state_receiver_address" yaml:"state_receiver_address"`

 // ValidatorSetAddress is valid contract address
 ValidatorSetAddress  hmTypes.HeimdallAddress `json:"validator_set_address" yaml:"validator_set_address"`
}

CLI commands

Parameters

To print all params;

heimdallcli query chainmanager params --trust-node

Expected result

tx_confirmation_time: 12s
chain_params:
  bor_chain_id: "1370"
  rama_token_address: "0x0000000000000000000000000000000000000000"
  staking_manager_address: "0x0000000000000000000000000000000000000000"
  root_chain_address: "0x0000000000000000000000000000000000000000"
  staking_info_address: "0x0000000000000000000000000000000000000000"
  state_sender_address: "0x0000000000000000000000000000000000000000"
  state_receiver_address: "0x0000000000000000000000000000000000000000"
  validator_set_address: "0x0000000000000000000000000000000000000000"

REST APIs

Name

Method

URL

Params

GET

chainmanager/params

All query APIs will provide response in the following format:

{
 "height": "1",
 "result": {
  ...   
 }
}

Governance

Heimdall’s governance operates identically to the Cosmos-sdk x/gov module, as detailed in Cosmos-sdk documentation.

Overview

In Heimdall, token holders can influence decisions by voting on proposals. Each token equals one vote. The governance system currently supports:

Proposal submission: Validators can submit proposals along with a deposit. If the deposit reaches the minimum threshold within a set period, the proposal moves to a voting phase. Validators can reclaim their deposits after the proposal’s acceptance or rejection.
Voting: Validators are eligible to vote on proposals that have met the minimum deposit requirement.

The governance module includes two critical periods: the deposit and voting periods. Proposals failing to meet the minimum deposit by the end of the deposit period are automatically rejected. Upon reaching the minimum deposit, the voting period commences, during which validators cast their votes. After the voting period, the gov/Endblocker.go script tallies the votes and determines the proposal’s fate based on tally_params: quorum, threshold, and veto. The tallying process is detailed in the source code at Heimdall GitHub repository.

Types of proposals

Currently, Heimdall supports the Param Change Proposal, allowing validators to modify parameters in any of Heimdall’s modules.

Param Change Proposal example

For instance, validators might propose to alter the minimum tx_fees in the auth module. If the proposal is approved, the parameters in the Heimdall state are automatically updated without the need for an additional transaction.

Command Line Interface (CLI) commands

Checking governance parameters

To view all parameters for the governance module:

heimdallcli query gov params --trust-node

This command displays the current governance parameters, such as voting period, quorum, threshold, veto, and minimum deposit requirements.

Submitting a proposal

To submit a proposal:

heimdallcli tx gov submit-proposal \
 --validator-id 1 param-change proposal.json \
 --chain-id <heimdall-chain-id>

proposal.json is a JSON-formatted file containing the proposal details.

Querying proposals

To list all proposals:

heimdallcli query gov proposals --trust-node

To query a specific proposal:

heimdallcli query gov proposal 1 --trust-node

Voting on a proposal

To vote on a proposal:

heimdallcli tx gov vote 1 "Yes" --validator-id 1 --chain-id <heimdall-chain-id>

Votes are automatically tallied after the voting period concludes.

REST APIs

Heimdall also offers REST APIs for interacting with the governance system:

Name

Method

Endpoint

Get all proposals

GET

/gov/proposals

Get proposal details

GET

/gov/proposals/{proposal-id}

Get all votes for a proposal

GET

/gov/proposals/{proposal-id}/votes

These APIs facilitate access to proposal details, voting records, and overall governance activity.

PreviousArchitecture NextBor

Last updated 10 months ago

Heimdall and Bor

Messages

MsgProposeSpan

Types

Parameters

CLI Commands

Span propose tx

Query current span

Query span by id

Parameters

REST APIs

Authentication

Gas and fees

Types

StdSignature

StdTx

StdSignDoc

Account

Parameters

CLI commands

Show account

Account and coin details

Parameters

REST APIs

Key management

Signer key

Owner key

Signer change

Advanced Gas Management in Heimdall

Block and Transaction Gas Limits

Enhanced Transaction Verification and Replay Protection

Sequence Number for Replay Protection

Balance transfers

Messages

MsgSend

MsgMultiSend

Parameters

CLI Commands

Send Balance

Staking

Messages

MsgValidatorJoin

MsgStakeUpdate

MsgValidatorExit

MsgSignerUpdate

CLI Commands

Validator details

Validator join

REST APIs

Checkpoint life-cycle and types

Life-cycle

Types and structures

AccountRootHash

Messages in checkpoint module

MsgCheckpoint

MsgCheckpointAck

MsgCheckpointNoAck

Parameters and CLI commands

Parameters

CLI commands

Printing all parameters

Send Checkpoint

Send ack

Send no-ack

REST APIs

Topup

Messages

MsgTopup

MsgWithdrawFee

CLI Commands

Topup fee

Withdraw fee

REST APIs

Chain management

Types

CLI commands

Parameters

Expected result

REST APIs

Governance

Send `ack`

Send `no-ack`