Checkpoint
Overview
checkpoint
module manages checkpoint related functionalities for Heimdall. It needs Bor chain when a new checkpoint is proposed on Heimdall to verify checkpoint root hash.
All related to checkpoint data is explained in details here:
Checkpoint life-cycle
The following flow chart represents the life cycle of the checkpoint. Heimdall uses the same leader selection algorithm as Tendermint to select the next proposer.
While submitting checkpoints on the Ethereum chain, it may fail due to multiple reasons like gas limit, traffic on Ethereum, high gas fees. That's why the multi-stage checkpoint process is required.
Since each checkpoint has validator as proposer. If checkpoint on Ethereum chain fails or succeeds, ack
and no-ack
transaction would change the proposer on Heimdall for next checkpoint.
Messages
MsgCheckpoint
MsgCheckpoint
handles checkpoint verification on Heimdall. Only this message uses RLP encoding to since it needs to be verified on Ethereum chain.
Once this transaction gets processed on Heimdall, the proposer
takes votes
and sigs
from Tendermint for this transaction and sends checkpoint on the Ethereum chain.
Since block contains multiple transactions and verifies this particular transaction on the Ethereum chain, Merkle proof is required. To avoid extra Merkle proof verification on Ethereum, Heimdall only allows one transaction in the block if the transaction type is MsgCheckpoint
To allow this mechanism, Heimdall sets MsgCheckpoint
transaction as high gas consumed transaction. Check https://github.com/maticnetwork/heimdall/blob/develop/auth/ante.go#L104-L106
This transaction will store proposed checkpoint on checkpointBuffer
state instead of actual checkpoint list state.
MsgCheckpointAck
MsgCheckpointAck
handles successful checkpoint submission. Here HeaderBlock
is a checkpoint counter.
For valid TxHash
and LogIndex
for the submitted checkpoint, this transaction verifies the following event and validates checkpoint in checkpointBuffer
state: https://github.com/maticnetwork/contracts/blob/develop/contracts/root/RootChainStorage.sol#L7-L14
On successful event verification, it updates the actual count of checkpoint, also known as ackCount
and clears the checkpointBuffer
MsgCheckpointNoAck
MsgCheckpointNoAck
handles un-successful checkpoints or offline proposers. This transaction is only valid after CheckpointBufferTime
has passed from the following events:
- Last successful
ack
transaction - Last successful
no-ack
transaction
This transaction gives the timeout period for the current proposer to send checkpoint/ack before Heimdall chooses a new proposer
for the next checkpoint.
Parameters
The checkpoint module contains the following parameters:
Key | Type | Default value |
---|---|---|
CheckpointBufferTime | uint64 | 1000 * time.Second |
CLI commands
Params
To print all params
Expected Result:
Send checkpoint
Following command sends checkpoint transaction on Heimdall:
Send ack
Following command sends ack transaction on Heimdall if checkpoint is successful on Ethereum:
Send no-ack
Following command send no-ack transaction on Heimdall:
REST APIs
Name | Method | Endpoint |
---|---|---|
Get current checkpoint buffer state | GET | /checkpoint/buffer |
Get checkpoint counts | GET | /checkpoint/count |
Get checkpoint details by block index | GET | /checkpoint/headers/<header-block-index> |
Get latest checkpoint | GET | /checkpoint/latest-checkpoint |
Get last no-ack details | GET | /checkpoint/last-no-ack |
Checkpoint details for given start and end block | GET | /checkpoint/<start>/<end> |
Checkpoint by number | GET | /checkpoint/<checkpoint-number> |
All checkpoints | GET | /checkpoint/list |
Get ack count, buffer, validator set, validator count and last-no-ack details | GET | /overview |
All query APIs will result in following format: