checkpoint

README

Checkpoint Module

Table of Contents

• Overview
• Interact with the Node
  • Tx Commands
  • CLI Query Commands
  • GRPC Endpoints
  • REST Endpoints

Overview

Heimdall selects the next proposer using Peppermint’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.

Messages

MsgCheckpoint

MsgCheckpoint defines a message for creating a checkpoint on the Ethereum chain.

message MsgCheckpoint {
option (cosmos.msg.v1.signer) = "proposer";
option (amino.name) = "checkpoint/MsgCheckpoint";

option (gogoproto.equal) = true;
option (gogoproto.goproto_getters) = true;

string proposer = 1 [
(amino.dont_omitempty) = true,
(cosmos_proto.scalar) = "cosmos.AddressString"
];

uint64 start_block = 2 [ (amino.dont_omitempty) = true ];

uint64 end_block = 3 [ (amino.dont_omitempty) = true ];

bytes root_hash = 4 [ (amino.dont_omitempty) = true ];

bytes account_root_hash = 5 [ (amino.dont_omitempty) = true ];

string bor_chain_id = 6 [ (amino.dont_omitempty) = true ];
}

MsgCpAck

MsgCpAck defines a message for creating the ack tx of a submitted checkpoint.

message MsgCpAck {
option (cosmos.msg.v1.signer) = "from";
option (amino.name) = "checkpoint/MsgCpAck";

option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = true;

string from = 1 [
(amino.dont_omitempty) = true,
(cosmos_proto.scalar) = "cosmos.AddressString"
];

uint64 number = 2 [ (amino.dont_omitempty) = true ];

string proposer = 3 [
(amino.dont_omitempty) = true,
(cosmos_proto.scalar) = "cosmos.AddressString"
];

uint64 start_block = 4 [ (amino.dont_omitempty) = true ];

uint64 end_block = 5 [ (amino.dont_omitempty) = true ];

bytes root_hash = 6 [ (amino.dont_omitempty) = true ];

bytes tx_hash = 7 [ (amino.dont_omitempty) = true ];

uint64 log_index = 8 [ (amino.dont_omitempty) = true ];
}

MsgCheckpointNoAck

MsgCheckpointNoAck defines a message for creating the no-ack tx of a checkpoint.

message MsgCheckpointNoAck {
option (cosmos.msg.v1.signer) = "from";

option (amino.name) = "checkpoint/MsgCheckpointNoAck";

option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = true;

string from = 1 [
(amino.dont_omitempty) = true,
(cosmos_proto.scalar) = "cosmos.AddressString"
];
}

Interact with the Node

Tx Commands

Send checkpoint

./build/heimdalld tx checkpoint send-checkpoint --proposer=<proposer-address> --start-block=<start-block-number> --end-block=<end-block-number> --root-hash=<root-hash> --account-root=<account-root> --bor-chain-id=<bor-chain-id> --chain-id=<chain-id> --auto-configure=true/false

Send checkpoint ack

./build/heimdalld tx checkpoint send-ack --tx-hash=<checkpoint-tx-hash> --log-index=<log-index> --header=<header> --proposer=<proposer-address> --chain-id=<heimdall-chainid>

Send checkpoint no-ack

./build/heimdalld tx checkpoint checkpoint-no-ack --from <from>

CLI Query Commands

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

• get-params - Get checkpoint params
• get-overview - Get checkpoint overview
• get-ack-count - Get checkpoint ack count
• get-checkpoint - Get checkpoint based on its number
• get-checkpoint-latest - Get the latest checkpoint
• get-checkpoint-buffer - Get the checkpoint buffer
• get-last-no-ack - Get the last no ack
• get-next-checkpoint - Get the next checkpoint
• get-current-proposer - Get the current proposer
• get-proposers - Get the proposers
• get-checkpoint-list - Get the list of checkpoints

./build/heimdalld query checkpoint get-params

./build/heimdalld query checkpoint get-overview

./build/heimdalld query checkpoint get-ack-count

./build/heimdalld query checkpoint get-checkpoint

./build/heimdalld query checkpoint get-checkpoint-latest

./build/heimdalld query checkpoint get-checkpoint-buffer

./build/heimdalld query checkpoint get-last-no-ack

./build/heimdalld query checkpoint get-next-checkpoint

./build/heimdalld query checkpoint get-current-proposer

./build/heimdalld query checkpoint get-proposers

./build/heimdalld query checkpoint get-checkpoint-list

GRPC Endpoints

The endpoints and the params are defined in the checkpoint/query.proto file. Please refer them for more information about the optional params.

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetCheckpointParams

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetCheckpointOverview

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetAckCount

grpcurl -plaintext -d '{"number": <>}' localhost:9090 heimdallv2.checkpoint.Query/GetCheckpoint

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetCheckpointLatest

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetCheckpointBuffer

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetLastNoAck

grpcurl -plaintext -d '{"bor_chain_id": <>}' localhost:9090 heimdallv2.checkpoint.Query/GetNextCheckpoint

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetCurrentProposer

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetProposers

grpcurl -plaintext -d '{}' localhost:9090 heimdallv2.checkpoint.Query/GetCheckpointList

grpcurl -plaintext -d '{"tx_hash": <>}' localhost:9090 heimdallv2.checkpoint.QueryGetCheckpointSignatures

REST Endpoints

The endpoints and the params are defined in the checkpoint/query.proto file. Please refer them for more information about the optional params.

curl localhost:1317/checkpoints/params

curl localhost:1317/checkpoints/overview

curl localhost:1317/checkpoints/count

curl localhost:1317/checkpoints/latest

curl localhost:1317/checkpoints/buffer

curl localhost:1317/checkpoints/last-no-ack

curl localhost:1317/checkpoints/prepare-next/{bor-chain-id}

curl localhost:1317/checkpoint/proposers/current

curl localhost:1317/checkpoint/proposers/{times}

curl localhost:1317/checkpoints/list

curl localhost:1317/checkpoint/signatures/{tx_hash}

curl localhost:1317/checkpoints/{number}

Documentation

Index

• Constants
• type AppModule
  • func NewAppModule(keeper *keeper.Keeper) 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 cdctypes.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/checkpoint module consensus version.

Types

type AppModule

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

AppModule implements an application module for the checkpoint module.

func NewAppModule

func NewAppModule(
	keeper *keeper.Keeper,
) AppModule

NewAppModule creates a new AppModule object

func (AppModule) AutoCLIOptions

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

AutoCLIOptions returns the auto cli options for the module (query and tx)

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 checkpoint 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 checkpoint 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 checkpoint module.

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 checkpoint module's name.

func (AppModule) QuerierRoute

func (AppModule) QuerierRoute() string

QuerierRoute returns the checkpoint 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 checkpoint module.

func (AppModule) RegisterInterfaces

func (AppModule) RegisterInterfaces(registry cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types

func (AppModule) RegisterLegacyAminoCodec

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

RegisterLegacyAminoCodec registers the checkpoint module's types on the given 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 side handler module services.

func (AppModule) ValidateGenesis

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

ValidateGenesis performs genesis state validation for the checkpoint module.