bor

README

Bor module

Table of Contents

• Preliminary terminology
• Overview
• How does it work
  • How to propose a span
• Query commands

Preliminary terminology

• A side-transaction is a normal heimdall transaction but the data with which the message is composed needs to be voted on by the validators since the data is obscure to the consensus protocol itself, and it has no way of validating the data's correctness.
• A sprint comprises of 16 bor blocks (configured in bor).
• A span comprises of 400 sprints in bor (check heimdall's bor params endpoint ).

Overview

The validators on bor chain produce blocks in sprints and spans. Hence, it is imperative for the protocol to formalise the validators who will be producers in a range of blocks (span). The bor module in heimdall facilitates this by pseudo-randomly selecting validators who will producing blocks (producers) from the current validator set. The bor chain fetches and persists this information before the next span begins. bor module is a crucial component in heimdall since the PoS chain "liveness" depends on it.

How does it work

A Span is defined by the data structure:

message Span {
	uint64 id = 1;
	uint64 start_block = 2;
	uint64 end_block = 3;
	heimdallv2.stake.ValidatorSet validator_set = 4
	[ (gogoproto.nullable) = false ];
	repeated heimdallv2.stake.Validator selected_producers = 5
	[ (gogoproto.nullable) = false ];
	string chain_id = 6;
}

where ,

• id means the id of the span, calculated by monotonically incrementing the id of the previous span.
• start_block corresponds to the block in bor from which the given span would commence.
• end_block corresponds to the block in bor at which the given span would conclude.
• validator_set defines the set of active validators.
• selected_producers are the validators selected to produce blocks in bor from the validator set.
• chain_id corresponds to bor chain ID.

A validator on heimdall can construct a span proposal message:

message MsgProposeSpan {
	option (cosmos.msg.v1.signer) = "proposer";

	uint64 span_id = 1;
	string proposer = 2 [ (cosmos_proto.scalar) = "cosmos.AddressString" ];
	uint64 start_block = 3;
	uint64 end_block = 4;
	string chain_id = 5;
	bytes seed = 6;
}

The msg is generally constructed and broadcast by the validator's bridge process periodically, but the CLI can also be leveraged to do the same manually (see below). Upon broadcasting the message, it is initially checked by ProposeSpan handler for basic sanity (verify whether the proposed span is in continuity, appropriate span duration, correct chain ID, etc.). Since this is a side-transaction, the validators then vote on the data present in MsgProposeSpan on the basis of its correctness. All these checks are done in SideHandleMsgSpan (verifying seed, span continuity, etc.) and if correct, the validator would vote YES. Finally, if there are 2/3+ YES votes, the PostHandleMsgSpan persists the proposed span in the state via the keeper :

// freeze for new span
err = s.k.FreezeSet(ctx, msg.SpanId, msg.StartBlock, msg.EndBlock, msg.ChainId, common.Hash(msg.Seed))
if err != nil {
	s.k.Logger(ctx).Error("Unable to freeze validator set for span", "span id", msg.SpanId, "error", err)
	return

}

FreezeSet internally invokes SelectNextProducers, which pseudo-randomly picks producers from the validator set, leaning more towards validators with higher voting power based on stake:

// select next producers
newProducers, err := k.SelectNextProducers(ctx, seed)
if err != nil {
	return err
}

and then initialises and stores the span:

newSpan := &types.Span{
	Id:                id,
	StartBlock:        startBlock,
	EndBlock:          endBlock,
	ValidatorSet:      k.sk.GetValidatorSet(ctx),
	SelectedProducers: newProducers,
	ChainId:           borChainID,
}

return k.AddNewSpan(ctx, newSpan)

How to propose a span

A validator can leverage the CLI to propose a span like so :

./build/heimdalld tx bor propose-span --proposer <VALIDATOR_ADDRESS> --start-block <BOR_START_BLOCK> --span-id <SPAN_ID> --bor-chain-id <BOR_CHAIN_ID>

Query commands

One can run the following query commands from the bor module :

• span - Query the span corresponding to the given span id.
• latest span - Query the latest span.
• params - Fetch the parameters associated to bor module.
• spanlist - Fetch span list.
• next-span-seed - Query the seed for the next span.
• propose-span - Print the propose-span command.

CLI commands

./build/heimdalld query bor span-by-id <SPAN_ID>

./build/heimdalld query bor latest-span

./build/heimdalld query bor params

./build/heimdalld query bor span-list

./build/heimdalld query bor next-span-seed

./build/heimdalld tx bor propose-span --proposer <VALIDATOR_ADDRESS> --start-block <BOR_START_BLOCK> --span-id <SPAN_ID> --bor-chain-id <BOR_CHAIN_ID>

REST endpoints

curl localhost:1317/bor/span/<SPAN_ID>

curl localhost:1317/bor/span/list

curl localhost:1317/bor/span/latest

curl localhost:1317/bor/params

curl localhost:1317/bor/span/seed

curl "localhost:1317/bor/span/prepare?span_id=<SPAN_ID>&start_block=<BOR_START_BLOCK>&chain_id="<BOR_CHAIN_ID>""

Documentation

Index

• Constants
• type AppModule
  • func NewAppModule(keeper keeper.Keeper, contractCaller helper.IContractCaller) AppModule
  • func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions
  • func (AppModule) ConsensusVersion() uint64
  • func (AppModule) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage
  • func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage
  • func (am AppModule) GetTxCmd() *cobra.Command
  • func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, data json.RawMessage)
  • func (am AppModule) IsAppModule()
  • func (am AppModule) IsOnePerModuleType()
  • func (AppModule) Name() string
  • func (AppModule) QuerierRoute() string
  • func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)
  • func (AppModule) RegisterInterfaces(registry codectypes.InterfaceRegistry)
  • func (AppModule) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)
  • func (am AppModule) RegisterServices(cfg module.Configurator)
  • func (am AppModule) RegisterSideMsgServices(sideCfg sidetxs.SideTxConfigurator)
  • func (AppModule) ValidateGenesis(cdc codec.JSONCodec, _ client.TxEncodingConfig, bz json.RawMessage) error

Constants

const ConsensusVersion = 1

ConsensusVersion defines the current x/bor module consensus version.

Types

type AppModule

type AppModule struct {
	// contains filtered or unexported fields
}

AppModule implements an application module for the bor module.

func NewAppModule

func NewAppModule(
	keeper keeper.Keeper,
	contractCaller helper.IContractCaller,
) AppModule

NewAppModule creates a new AppModule object

func (AppModule) AutoCLIOptions

func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements AppModule/ConsensusVersion.

func (AppModule) DefaultGenesis

func (AppModule) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns default genesis state as raw bytes for the bor module.

func (AppModule) ExportGenesis

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the exported genesis state as raw bytes for the bor module.

func (AppModule) GetTxCmd

func (am AppModule) GetTxCmd() *cobra.Command

GetTxCmd returns the root tx command for the bor module.

func (AppModule) InitGenesis

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, data json.RawMessage)

InitGenesis performs genesis initialization for the bor module. It returns no validator updates.

func (AppModule) IsAppModule

func (am AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType

func (am AppModule) IsOnePerModuleType()

IsOnePerModuleType implements the depinject.OnePerModuleType interface.

func (AppModule) Name

func (AppModule) Name() string

Name returns the bor module's name.

func (AppModule) QuerierRoute

func (AppModule) QuerierRoute() string

QuerierRoute returns the bor module's querier route name.

func (AppModule) RegisterGRPCGatewayRoutes

func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the bor module.

func (AppModule) RegisterInterfaces

func (AppModule) RegisterInterfaces(registry codectypes.InterfaceRegistry)

RegisterInterfaces registers interfaces and implementations of the bor module.

func (AppModule) RegisterLegacyAminoCodec

func (AppModule) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

RegisterLegacyAminoCodec registers the bor module's types on the LegacyAmino codec.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers module services.

func (AppModule) RegisterSideMsgServices

func (am AppModule) RegisterSideMsgServices(sideCfg sidetxs.SideTxConfigurator)

RegisterSideMsgServices registers the side message services for the bor module.

func (AppModule) ValidateGenesis

func (AppModule) ValidateGenesis(cdc codec.JSONCodec, _ client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the bor module.