qgb

package
v1.0.0-rc0 Latest Latest
Warning

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

 Go to latest Published: May 24, 2023 License: Apache-2.0 Imports: 17 Imported by: 0

README

x/qgb

Abstract

This module contains the Quantum Gravity Bridge (QGB) state machine implementation.

State machine

The QGB state machine handles the creation of AttestationRequestI which can be either a DataCommitment or a Valset.

During their creation, the state machine might panic due to an unexpected behavior or event. These panics will be discussed below.

Conditions of generating a new attestation
New valset creation

A new valset is created in the following situations:

if (latestValset == nil) || (lastUnbondingHeight == uint64(ctx.BlockHeight())) || significantPowerDiff {
    ...
}
  • No valset exists in store, so a new valset will be created. This happens mostly after genesis, or after a hard fork.
  • The current block height is the last unbonding height, i.e. when a validator is leaving the validator set. A new valset will need to be created to accommodate that change.
  • A significant power difference happened since the last valset. This could happen if a validator has way more staking power or the opposite. The significant power difference threshold is defined by the constant SignificantPowerDifferenceThreshold, and is set to 5% currently.
New data commitment creation

A new data commitment is created in the following situation:

if ctx.BlockHeight() != 0 && ctx.BlockHeight()%int64(k.GetDataCommitmentWindowParam(ctx)) == 0 {
	...
}

I.e. the current block height is not 0, and we're at a data commitment window height.

The data commitment window is defined as a governance parameter that can be changed. Currently, it is set to 400.

Panics

During EndBlock step, the state machine generates new attestations if needed. During this generation, the state machine could panic.

Valset panics

When checking if the state machine needs to generate a new valset, the state machine might panic if it finds invalid state. This can happen in the following cases:

  • When checking that a previous valset has been emitted, but it is unable to get it:
if k.CheckLatestAttestationNonce(ctx) && k.GetLatestAttestationNonce(ctx) != 0 {  
   var err error  
   latestValset, err = k.GetLatestValset(ctx)  
   if err != nil {  
      panic(err)  
   }  
}
  • When getting the current valset:
vs, err := k.GetCurrentValset(ctx)
if err != nil {  
   // this condition should only occur in the simulator  
   // ref : https://github.com/Gravity-Bridge/Gravity-Bridge/issues/35 
   if errors.Is(err, types.ErrNoValidators) {  
      ctx.Logger().Error("no bonded validators",  
         "cause", err.Error(),  
      )  
      return  
   }  
   panic(err)  
}
  • When creating the internal validator struct, i.e. mapping the validators EVM addresses to their powers:
intLatestMembers, err := types.BridgeValidators(latestValset.Members).ToInternal()  
if err != nil {  
   panic(sdkerrors.Wrap(err, "invalid latest valset members"))  
}
Attestations panics

When storing a new attestation, the state machine can panic if it finds invalid state. This latter can happen in the following cases:

  • The attestation request created is a duplicate of an existing attestation:
key := []byte(types.GetAttestationKey(nonce))  
store := ctx.KVStore(k.storeKey)  
  
if store.Has(key) {  
   panic("trying to overwrite existing attestation request")  
}
  • An error happened while marshalling the interface:
b, err := k.cdc.MarshalInterface(at)  
if err != nil {  
   panic(err)  
}
  • The universal nonce was not incremented correctly by 1:
if k.CheckLatestAttestationNonce(ctx) && k.GetLatestAttestationNonce(ctx)+1 != nonce {  
   panic("not incrementing latest attestation nonce correctly")  
}

Verification command

The QGB verification command is part of the celestia-appd binary. It allows the user to verify that a set of shares has been posted to a specific QGB contract.

$ celestia-appd verify --help          
                              
Verifies that a transaction hash, a range of shares, or a blob referenced by its transaction hash were committed to by the QGB contract

Usage:
  celestia-appd verify [command]

Available Commands:
  blob        Verifies that a blob, referenced by its transaction hash, in hex format, has been committed to by the QGB contract.
  shares      Verifies that a range of shares has been committed to by the QGB contract
  tx          Verifies that a transaction hash, in hex format, has been committed to by the QGB contract

Flags:
  -h, --help   help for verify

Global Flags:
      --home string         directory for config and data (default "/home/midnight/.celestia-app")
      --log_format string   The logging format (json|plain) (default "plain")
      --log_level string    The logging level (trace|debug|info|warn|error|fatal|panic) (default "info")
      --trace               print out full stack trace on errors

Use "celestia-appd verify [command] --help" for more information about a command.

It currently supports three sub-commands:

  • blob: Takes a transaction hash, in hex format, and verifies that the blob paid for by the transaction has been committed to by the QGB contract. It only supports one blob for now.
  • shares: Takes a range of shares and a height, and verifies that these shares have been committed to by the QGB contract.
  • tx: Takes a transaction hash, in hex format, and verifies that it has been committed to by the QGB contract.

The smart contract implementation is in quantum-gravity-bridge.

For QGB v2, the orchestrator and relayer implementations will be in a separate repository. Links will be added subsequently.

QGB v1 implementation, including the orchestrator and relayer, is in the qgb-integration branch.

QGB ADRs are in the docs.

Documentation

Index

Constants

View Source 
const (
	// SignificantPowerDifferenceThreshold is the threshold of change in the validator set power
	// that would trigger the creation of a new valset request.
	SignificantPowerDifferenceThreshold = 0.05

	// AttestationExpiryTime is the expiration time of an attestation.
	// When this much time has passed after an attestation has been published, it will be
	// pruned from state.
	AttestationExpiryTime = 3 * oneWeek // 3 weeks
)

Variables

This section is empty.

Functions

func EndBlocker added in v0.7.0 

func EndBlocker(ctx sdk.Context, k keeper.Keeper)

EndBlocker is called at the end of every block.

func ExportGenesis 

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

ExportGenesis returns the capability module's exported genesis.

func InitGenesis 

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

InitGenesis initializes the capability module's state from a provided genesis state.

func NewHandler 

func NewHandler(_ keeper.Keeper) sdk.Handler

Can be deleted after implementing the Orchestrator and Relayer as per QGB ADR-005. NewHandler uses the provided qgb keeper to create an sdk.Handler.

Types

type AppModule 

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

AppModule implements the AppModule interface for the capability module.

func NewAppModule 

func NewAppModule(cdc codec.Codec, keeper keeper.Keeper) AppModule

func (AppModule) BeginBlock 

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

BeginBlock executes all ABCI BeginBlock logic respective to the capability module.

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements ConsensusVersion.

func (AppModule) EndBlock 

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

EndBlock executes all ABCI EndBlock logic respective to the capability module. It returns no validator updates.

func (AppModule) ExportGenesis 

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

ExportGenesis returns the capability module's exported genesis state as raw JSON bytes.

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs the capability module's genesis initialization It returns no validator updates.

func (AppModule) LegacyQuerierHandler 

func (am AppModule) LegacyQuerierHandler(_ *codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler returns the capability module's Querier.

func (AppModule) Name 

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) QuerierRoute 

func (AppModule) QuerierRoute() string

QuerierRoute returns the capability module's query routing key.

func (AppModule) RegisterInvariants 

func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants registers the capability module's invariants.

func (AppModule) RegisterServices 

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

RegisterServices registers a GRPC query service to respond to the module-specific GRPC queries.

func (AppModule) Route 

func (am AppModule) Route() sdk.Route

Route returns the capability module's message routing key.

type AppModuleBasic 

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

AppModuleBasic implements the AppModuleBasic interface for the capability module.

func NewAppModuleBasic 

func NewAppModuleBasic(cdc codec.BinaryCodec) AppModuleBasic

func (AppModuleBasic) DefaultGenesis 

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

DefaultGenesis returns the capability module's default genesis state.

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the capability module's root query command.

func (AppModuleBasic) GetTxCmd 

func (a AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the capability module's root tx command.

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

Name returns the capability module's name.

func (AppModuleBasic) RegisterCodec 

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

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(_ client.Context, _ *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the module.

func (AppModuleBasic) RegisterInterfaces 

func (a AppModuleBasic) RegisterInterfaces(reg cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types.

func (AppModuleBasic) RegisterLegacyAminoCodec 

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

func (AppModuleBasic) RegisterRESTRoutes 

func (AppModuleBasic) RegisterRESTRoutes(_ client.Context, _ *mux.Router)

RegisterRESTRoutes registers the capability module's REST service handlers.

func (AppModuleBasic) ValidateGenesis 

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

ValidateGenesis performs genesis state validation for the capability module.

Source Files

View all Source files

Directories

Path Synopsis
Package types is a reverse proxy.
 Package types is a reverse proxy.

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.