Heimdall Layer

Heimdall is the backbone of Shibarium’s validator and state management, built on a customized Cosmos-SDK and a forked Tendermint (Peppermint). It manages validators, block producer selection, spans, state sync between Ethereum and Shibarium, and more.

Architecture Overview

Manages Validators: Handles validator set, power, and selection.
Span & Producer Selection: Allocates slots and shuffles for fair, weighted block producer selection.
State Sync: Relays and commits state between Ethereum and Shibarium.
Governance: Parameter changes and voting via on-chain proposals.

Diagram showing Heimdall as the validator/state management layer between Ethereum and Bor.

Heimdall's role in Shibarium PoS architecture

Validator & Producer Selection

Slot Allocation Shibd on Validator Power

Each validator receives slots proportional to their power (e.g., power 10 = 10 slots). Higher power = higher chance of selection.

Shuffling & Selection

Slots are shuffled using a seed from the Ethereum block hash for each span. The first producerCount are selected as block producers using the Ethereum 2.0 shuffle algorithm.

Span Structure & Producer Selection Code

// 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"`
}

// Producer selection
func SelectNextProducers(blkHash common.Hash, spanEligibleVals []hmTypes.Validator, producerCount uint64) (selectedIDs []uint64, err error) {
 // ...see official docs for full code
}

Span & Producer Parameters

Key	Type	Default value	Duration
SprintDuration	uint64	16 blocks	32 seconds
SpanDuration	uint64	100 * SprintDuration = 1,600 blocks	3,200 seconds (~53 min)
ProducerCount	uint64	4 blocks	8 seconds

Messages & Types

MsgProposeSpan

// 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"`
}

ChainParams Structure

type ChainParams struct {
 BorChainID            string                  `json:"bor_chain_id" yaml:"bor_chain_id"`
 StakingManagerAddress hmTypes.HeimdallAddress `json:"staking_manager_address" yaml:"staking_manager_address"`
 RootChainAddress      hmTypes.HeimdallAddress `json:"root_chain_address" yaml:"root_chain_address"`
 StakingInfoAddress    hmTypes.HeimdallAddress `json:"staking_info_address" yaml:"staking_info_address"`
 StateSenderAddress    hmTypes.HeimdallAddress `json:"state_sender_address" yaml:"state_sender_address"`
 StateReceiverAddress  hmTypes.HeimdallAddress `json:"state_receiver_address" yaml:"state_receiver_address"`
 ValidatorSetAddress   hmTypes.HeimdallAddress `json:"validator_set_address" yaml:"validator_set_address"`
}

CLI Commands

Span Management

Propose a span:

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>

Query span by id:

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

Parameters & Chain Management

Governance

View governance params:

heimdallcli query gov params --trust-node

Submit a proposal:

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

List all proposals:

heimdallcli query gov proposals --trust-node

Query a proposal:

heimdallcli query gov proposal 1 --trust-node

Vote on a proposal:

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

REST APIs

Name	Method	Endpoint
Span details	GET	/bor/span/span-id
Get latest span	GET	/bor/latest-span
Get params	GET	/bor/params
Chain params	GET	chainmanager/params
All proposals	GET	/gov/proposals
Proposal detail	GET	/gov/proposals/
Proposal votes	GET	/gov/proposals//votes

Governance Overview

Proposal Submission: Validators submit proposals with a deposit. If the deposit threshold is met, voting begins.
Voting: Validators vote on proposals. Each BONE token = 1 vote.
Tallying: After the voting period, votes are tallied based on quorum, threshold, and veto parameters.
Param Change Proposals: Used to update Heimdall module parameters (e.g., tx fees).

Quickstart

How-tos

Architecture

Architecture Overview

Validator & Producer Selection

Messages & Types

CLI Commands

REST APIs

Governance Overview

Quickstart

How-tos

Architecture

​Architecture Overview

​Validator & Producer Selection

​Messages & Types

​CLI Commands

​REST APIs

​Governance Overview

Architecture Overview

Validator & Producer Selection

Messages & Types

CLI Commands

REST APIs

Governance Overview