Shibarium
Search
K

Heimdall

Heimdall is the heart of the Shibarium network. It manages validators, block producer selection, spans, the state-sync mechanism between Ethereum and Shibarium and other essentials 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 customised 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. 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. 2.
    Shuffling and Selection: All allocated slots are then shuffled using a seed derived from the Ethereum (ETH 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 Ethereum 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":"15001"
}

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
7
TxSizeCostPerByte
uint64
10
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: BONE
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 Shibarium. 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 Ethereum 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:
  • Bone tokens on Heimdall (through Topup transactions) to perform validator responsibilities on Heimdall
  • ETH on Ethereum chain to send checkpoints on Ethereum

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 Ethereum chain. The private key for this key must be secure at all cost.
All transactions through this key will be performed on the Ethereum chain.

Signer change

Following event is generated in case of signer change on Ethereum 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 Ethereum 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 Shibarium 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 bone tokens to mentioned address;
heimdallcli tx bank send <address> 1000bone --chain-id <chain-id>

Staking

Staking module manages validator related transactions and state for Heimdall. Note that a validator stakes their tokens on the Ethereum chain and becomes a validator. Respective validators send the transactions on Heimdall using necessary parameters to acknowledge the Ethereum 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 Ethereum, 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 Ethereum 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 Shibarium 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 Ethereum 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 Ethereum 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 Ethereum 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
Root Hash Image
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 Ethereum 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 Ethereum 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 Ethereum:
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:
  1. 1.
    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.
  2. 2.
    A user can directly call the top-up function on the staking smart contract on Ethereum to increase top-up balance on Heimdall.

Messages

MsgTopup

MsgTopup transaction is responsible for minting balance to an address on Heimdall based on Ethereum 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 Ethereum 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