clerk

package
v1.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2024 License: GPL-3.0 Imports: 27 Imported by: 0

README

Clerk Module

Table of Contents

Preliminary terminology

  • A StateSender is a contract deployed on L1 (Ethereum) responsible for emitting state-sync events.
  • A StateReceiver is a contract deployed on L2 (Bor) responsible for receiving state-sync events.
  • A EventRecord is a record of the state-sync event stored in the heimdall state.

Overview

Clerk manages generic event records from Ethereum blockchain related to state-sync events, These are specially designed events that are emitted by the StateSender contract on the L1 chain to notify the L2 nodes (Bor in case of PoS) about the state changes in the L1. Once the events are processed by the bridge, Clerk listens to these events and stores them in the database for further processing.

State-Sync Mechanism

It's a mechanism for state-management between Ethereum and Bor chain, The events generated are called state-sync events. This is a way to move data from the L1 chain to L2 chain.

State-Sync Mechanism

How does it work

An EventRecord is defined by the data structure :

type EventRecord struct {
	ID         uint64                `json:"id" yaml:"id"`
	Contract   types.HeimdallAddress `json:"contract" yaml:"contract"`
	Data       types.HexBytes        `json:"data" yaml:"data"`
	TxHash     types.HeimdallHash    `json:"tx_hash" yaml:"tx_hash"`
	LogIndex   uint64                `json:"log_index" yaml:"log_index"`
	ChainID    string                `json:"bor_chain_id" yaml:"bor_chain_id"`
	RecordTime time.Time             `json:"record_time" yaml:"record_time"`
}
  • ID is the unique identifier for the event record, Generated by the StateSender contract.
  • Contract is the address of the contract on the L2 chain on which the event will be processed.
  • Data is the data of the event which will be processed by the contract.
  • TxHash is the transaction hash of the event on the L1 chain.
  • LogIndex is the log index of the event on the L1 chain.
  • ChainID is the chain id of the bor chain.
  • RecordTime is the time at which the event was recorded in heimdall state.

The bridge will listen to the state-sync events from L1 and generate a txn with MsgEventRecord which is responsible for validating events from StateSender contract and storing the EventRecord on the heimdall state for bor to use.

type MsgEventRecord struct {
	From            types.HeimdallAddress `json:"from"`
	TxHash          types.HeimdallHash    `json:"tx_hash"`
	LogIndex        uint64                `json:"log_index"`
	BlockNumber     uint64                `json:"block_number"`
	ContractAddress types.HeimdallAddress `json:"contract_address"`
	Data            types.HexBytes        `json:"data"`
	ID              uint64                `json:"id"`
	ChainID         string                `json:"bor_chain_id"`
}

Handler for this transaction validates for multiple conditions including TxHash and LogIndex to ensure that the event exists on L1 and the data is not tampered with, It throws Older invalid tx found error if the event is already processed.

Once the event is validated by the Handler, It will go to SideHandleMsgEventRecord in each validator node and after verifying the event, The validators will vote with either a YES return an error for a failed verification.

Only when there is a majority of YES votes, The event will be processed by PostHandleMsgEventRecord which will persist the event in the state via keeper.

How to add an event

A validator can leverage the CLI to add an event to the state in case it's missing and not processed by the bridge, The CLI command is :

heimdallcli tx clerk record 
    --id <event-id>
    --contract <contract-address>
    --data <event-data>
    --tx-hash <tx-hash>
    --log-index <log-index>
    --block-number <L1-block-number>
    --bor-chain-id <bor-chain-id>
    --chain-id <heimdall-chain-id>

Query commands

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

  • record - Query for a specific event record.
  • list - Query a list of event records.
  • isoldtx - Query if the event record is already processed.
CLI commands
heimdallcli query clerk record --id <event-id>

heimdallcli query clerk is-old-tx --tx-hash <tx-hash> --log-index <log-index>
REST endpoints
curl -X GET "localhost:1317/clerk/event-record/<event-id>"

curl -X GET "localhost:1317/clerk/event-record/list?from-id=<from-id>&to-time=<time-in-unix>&limit=<limit>"

curl -X GET "localhost:1317/clerk/isoldtx?tx-hash=<tx-hash>&log-index=<log-index>"

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	StateRecordPrefixKey = []byte{0x11} // prefix key for when storing state

	// DefaultValue default value
	DefaultValue = []byte{0x01}

	// RecordSequencePrefixKey represents record sequence prefix key
	RecordSequencePrefixKey = []byte{0x12}

	StateRecordPrefixKeyWithTime = []byte{0x13} // prefix key for when storing state with time
)

Functions

func ExportGenesis 

func ExportGenesis(ctx sdk.Context, keeper Keeper) types.GenesisState

ExportGenesis returns a GenesisState for a given context and keeper.

func GetEventRecordKey 

func GetEventRecordKey(stateID uint64) []byte

GetEventRecordKey appends prefix to state id

func GetEventRecordKeyWithTime added in v0.1.7 

func GetEventRecordKeyWithTime(stateID uint64, recordTime time.Time) []byte

GetEventRecordKeyWithTime appends prefix to state id and record time

func GetEventRecordKeyWithTimePrefix added in v0.1.7 

func GetEventRecordKeyWithTimePrefix(recordTime time.Time) []byte

GetEventRecordKeyWithTimePrefix gives prefix for record time key

func GetRecordSequenceKey added in v0.1.5 

func GetRecordSequenceKey(sequence string) []byte

GetRecordSequenceKey returns record sequence key

func InitGenesis 

func InitGenesis(ctx sdk.Context, keeper Keeper, data types.GenesisState)

InitGenesis sets distribution information for genesis.

func NewHandler 

func NewHandler(k Keeper, contractCaller helper.IContractCaller) sdk.Handler

NewHandler creates new handler for handling messages for clerk module

func NewPostTxHandler added in v0.1.7 

func NewPostTxHandler(k Keeper, contractCaller helper.IContractCaller) hmTypes.PostTxHandler

NewPostTxHandler returns a side handler for "bank" type messages.

func NewQuerier 

func NewQuerier(keeper Keeper, contractCaller helper.IContractCaller) sdk.Querier

NewQuerier creates a querier for auth REST endpoints

func NewSideTxHandler added in v0.1.7 

func NewSideTxHandler(k Keeper, contractCaller helper.IContractCaller) hmTypes.SideTxHandler

NewSideTxHandler returns a side handler for "topup" type messages.

func PostHandleMsgEventRecord added in v0.1.7 

func PostHandleMsgEventRecord(ctx sdk.Context, k Keeper, msg types.MsgEventRecord, sideTxResult abci.SideTxResultType) sdk.Result

func SideHandleMsgEventRecord added in v0.1.7 

func SideHandleMsgEventRecord(ctx sdk.Context, k Keeper, msg types.MsgEventRecord, contractCaller helper.IContractCaller) (result abci.ResponseDeliverSideTx)

Types

type AppModule 

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

AppModule implements an application module for the clerk module.

func NewAppModule 

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

NewAppModule creates a new AppModule object

func (AppModule) BeginBlock 

func (AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

BeginBlock returns the begin blocker for the auth module.

func (AppModule) EndBlock 

func (AppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock returns the end blocker for the auth module. It returns no validator updates.

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context) json.RawMessage

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

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, data json.RawMessage) []abci.ValidatorUpdate

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

func (AppModule) Name 

func (AppModule) Name() string

Name returns the auth module's name.

func (AppModule) NewHandler 

func (am AppModule) NewHandler() sdk.Handler

NewHandler returns an sdk.Handler for the module.

func (AppModule) NewPostTxHandler added in v0.1.7 

func (am AppModule) NewPostTxHandler() hmTypes.PostTxHandler

NewPostTxHandler side tx handler

func (AppModule) NewQuerierHandler 

func (am AppModule) NewQuerierHandler() sdk.Querier

NewQuerierHandler returns the auth module sdk.Querier.

func (AppModule) NewSideTxHandler added in v0.1.7 

func (am AppModule) NewSideTxHandler() hmTypes.SideTxHandler

func (AppModule) QuerierRoute 

func (AppModule) QuerierRoute() string

QuerierRoute returns the auth module's querier route name.

func (AppModule) RegisterInvariants 

func (AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants performs a no-op.

func (AppModule) Route 

func (AppModule) Route() string

Route returns the message routing key for the auth module.

type AppModuleBasic 

type AppModuleBasic struct{}

AppModuleBasic defines the basic application module used by the auth module.

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis() json.RawMessage

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

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd(cdc *codec.Codec) *cobra.Command

GetQueryCmd returns the root query command for the auth module.

func (AppModuleBasic) GetTxCmd 

func (AppModuleBasic) GetTxCmd(cdc *codec.Codec) *cobra.Command

GetTxCmd returns the root tx command for the auth module.

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the auth module's name.

func (AppModuleBasic) RegisterCodec 

func (AppModuleBasic) RegisterCodec(cdc *codec.Codec)

RegisterCodec registers the auth module's types for the given codec.

func (AppModuleBasic) RegisterRESTRoutes 

func (AppModuleBasic) RegisterRESTRoutes(ctx context.CLIContext, rtr *mux.Router)

RegisterRESTRoutes registers the REST routes for the auth module.

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the auth module.

func (AppModuleBasic) VerifyGenesis 

func (AppModuleBasic) VerifyGenesis(bz map[string]json.RawMessage) error

VerifyGenesis performs verification on auth module state.

type Keeper 

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

Keeper stores all related data

func NewKeeper 

func NewKeeper(
	cdc *codec.Codec,
	storeKey sdk.StoreKey,
	paramSpace subspace.Subspace,
	codespace sdk.CodespaceType,
	chainKeeper chainmanager.Keeper,
) Keeper

NewKeeper create new keeper

func (Keeper) Codespace 

func (k Keeper) Codespace() sdk.CodespaceType

Codespace returns the codespace

func (*Keeper) GetAllEventRecords 

func (k *Keeper) GetAllEventRecords(ctx sdk.Context) (records []*types.EventRecord)

GetAllEventRecords get all state records

func (*Keeper) GetEventRecord 

func (k *Keeper) GetEventRecord(ctx sdk.Context, stateID uint64) (*types.EventRecord, error)

GetEventRecord returns record from store

func (*Keeper) GetEventRecordList 

func (k *Keeper) GetEventRecordList(ctx sdk.Context, page uint64, limit uint64) ([]types.EventRecord, error)

GetEventRecordList returns all records with params like page and limit

func (*Keeper) GetEventRecordListWithTime added in v0.1.7 

func (k *Keeper) GetEventRecordListWithTime(ctx sdk.Context, fromTime, toTime time.Time, page, limit uint64) ([]types.EventRecord, error)

GetEventRecordListWithTime returns all records with params like fromTime and toTime

func (*Keeper) GetRecordSequences added in v0.1.5 

func (k *Keeper) GetRecordSequences(ctx sdk.Context) (sequences []string)

GetRecordSequences checks if record already exists

func (*Keeper) HasEventRecord 

func (k *Keeper) HasEventRecord(ctx sdk.Context, stateID uint64) bool

HasEventRecord check if state record

func (*Keeper) HasRecordSequence added in v0.1.5 

func (k *Keeper) HasRecordSequence(ctx sdk.Context, sequence string) bool

HasRecordSequence checks if record already exists

func (*Keeper) IterateRecordSequencesAndApplyFn added in v0.1.5 

func (k *Keeper) IterateRecordSequencesAndApplyFn(ctx sdk.Context, f func(sequence string) error)

IterateRecordSequencesAndApplyFn iterate records and apply the given function.

func (*Keeper) IterateRecordsAndApplyFn 

func (k *Keeper) IterateRecordsAndApplyFn(ctx sdk.Context, f func(record types.EventRecord) error)

IterateRecordsAndApplyFn iterate records and apply the given function.

func (Keeper) Logger 

func (k Keeper) Logger(ctx sdk.Context) log.Logger

Logger returns a module-specific logger

func (*Keeper) SetEventRecord 

func (k *Keeper) SetEventRecord(ctx sdk.Context, record types.EventRecord) error

SetEventRecord adds record to store

func (*Keeper) SetEventRecordWithID added in v0.1.7 

func (k *Keeper) SetEventRecordWithID(ctx sdk.Context, record types.EventRecord) error

SetEventRecordWithID adds record to store with ID

func (*Keeper) SetEventRecordWithTime added in v0.1.7 

func (k *Keeper) SetEventRecordWithTime(ctx sdk.Context, record types.EventRecord) error

SetEventRecordWithTime sets event record id with time

func (*Keeper) SetRecordSequence added in v0.1.5 

func (k *Keeper) SetRecordSequence(ctx sdk.Context, sequence string)

SetRecordSequence sets mapping for sequence id to bool

Source Files

View all Source files

Directories

Path Synopsis
client
cli
rest
nolint
 nolint

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.