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

1

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.
2

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
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
}
KeyTypeDefault valueDuration
SprintDurationuint6416 blocks32 seconds
SpanDurationuint64100 * SprintDuration = 1,600 blocks3,200 seconds (~53 min)
ProducerCountuint644 blocks8 seconds

​
Messages & Types

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

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

  • 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>
  • Print all params:
heimdalldcli query bor params
  • Chain manager params:
heimdallcli query chainmanager params --trust-node
  • 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

NameMethodEndpoint
Span detailsGET/bor/span/span-id
Get latest spanGET/bor/latest-span
Get paramsGET/bor/params
Chain paramsGETchainmanager/params
All proposalsGET/gov/proposals
Proposal detailGET/gov/proposals/
Proposal votesGET/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).
⌘I