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.
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.
Types
Here are the span details that Heimdall uses:
Parameters
The Bor module contains the following parameters:
(*): Given that blocks are produced every 2 seconds on Bor.
CLI Commands
Span propose tx
Query current span
Expected output:
Query span by id
It prints the result in same format as above.
Parameters
To print all params;
Expected Result:
REST APIs
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.
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.
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.
Account
It manages addresses, coins and nonce for transactions. It also signs and validates transactions.
Parameters
The auth module contains the following parameters:
CLI commands
Show account
To print account related data into Heimdall;
Expected Result:
Account and coin details
To display account details, coins, sequence and account number;
Expected Result:
Parameters
To print all params;
Expected Result:
REST APIs
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
:
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:
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:
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:
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:
MsgMultiSend
MsgMultiSend
handles multi transfer between account for Heimdall.
Parameters
The bank module contains the following parameters:
CLI Commands
Send Balance
Following command will send 1000 Rama tokens to mentioned address
;
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:
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:
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.
Here is MsgStakeUpdate
message for Heimdall transaction:
MsgValidatorExit
MsgValidatorExit
handles the validator exit process after a validator initiates the exit process on Ethereum. It emits SignerUpdate
event.
Here is MsgValidatorExit
message for Heimdall transaction:
MsgSignerUpdate
MsgSignerUpdate
handles the signer update when a validator updates signer key on Ethereum. It emits SignerUpdate
event.
Here is MsgSignerUpdate
message for Heimdall transaction:
CLI Commands
Validator details
By signer address
This command should display the following output:
By validator address
This command should display the following output:
Validator join
This command sends validator join command through CLI:
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
All query APIs will result in following format:
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
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.
Pseudocode for the root hash for 1
to n
Bor blocks:
Here are some snippets of how checkpoint is created from Bor chain block headers.
Source:
AccountRootHash
AccountRootHash
is the hash of the validator account-related information that needs to pass to the Polygon chain at each checkpoint.
Pseudocode for the account root hash for 1
to n
Bor blocks:
Golang code for the account hash can be found here:
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.
MsgCheckpointAck
MsgCheckpointAck
manages successful checkpoint submissions, updating the checkpoint count and clearing the checkpointBuffer
.
MsgCheckpointNoAck
MsgCheckpointNoAck
deals with unsuccessful checkpoints or offline proposers, allowing a timeout period before selecting a new proposer.
Parameters and CLI commands
Parameters
The checkpoint module contains the following parameters:
CLI commands
Commands are available for various actions such as sending checkpoints, sending ack
or no-ack
transactions, and querying parameters.
Printing all parameters
Expected Result:
Send Checkpoint
Following command sends checkpoint transaction on Heimdall:
Send ack
ack
Following command sends ack transaction on Heimdall if checkpoint is successful on Polygon:
Send no-ack
no-ack
Following command send no-ack transaction on Heimdall:
REST APIs
Heimdall provides several REST APIs for interacting with the checkpoint module, including endpoints for preparing messages, querying checkpoints, and more.
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:
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.
CLI Commands
Topup fee
Withdraw fee
To check reflected topup on account run following command
REST APIs
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:
CLI commands
Parameters
To print all params;
Expected result
REST APIs
All query APIs will provide response in the following format:
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:
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:
proposal.json
is a JSON-formatted file containing the proposal details.
Querying proposals
To list all proposals:
To query a specific proposal:
Voting on a proposal
To vote on a proposal:
Votes are automatically tallied after the voting period concludes.
REST APIs
Heimdall also offers REST APIs for interacting with the governance system:
These APIs facilitate access to proposal details, voting records, and overall governance activity.
Last updated