spec

package
v3.2.1-near-experimental Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2024 License: Apache-2.0 Imports: 30 Imported by: 0

README

x/spec

Abstract

This document specifies the spec module of Lava Protocol.

A specification, also known as a spec, defines the APIs that a provider commits to providing to consumers. An example of a spec is the Ethereum JSON-RPC spec, which defines the properties of the chain, all supported API calls and their compute units, also known as CUs. Lava has multiple specs, and participants can add and modify specs using governance proposals. When adding a new blockchain, the first step to support a new chain in lava is to create a spec for it.

This document focuses on the specs' technical aspects and does not include current chain support in Lava. For more information on those, please visit Lava's official website.

Contents

Concepts

Spec

A chain spec consists of general properties of the chain and a list of interfaces it supports. To simplify the creation and maintenance of specs, they can import APIs from another spec. For example, the X testnet spec can import from the X mainnet spec, eliminating the need to redefine all of the interfaces. For more instructions on how to build a spec visit: https://github.com/lavanet/lava/blob/main/cookbook/README.md

type Spec struct {
	Index                         string                // chain unique index                           
	Name                          string                // description string of the spec
	Enabled                       bool                  // spec enabled/disable 
	AverageBlockTime              int64                 // average block time of the chain in msec
	MinStakeProvider              Coin                  // min stake for a provider to be active in the chain
	ProvidersTypes                Spec_ProvidersTypes   // determines if the spec is for lava or chains 
	Imports                       []string              // list of chains to import ApiCollections from
	ApiCollections                []*ApiCollection      // list of ApiCollections that defines all the interfaces and APIs of the chain
	Contributor                   []string              // list of contributors (public lava address {lava@...})
	ContributorPercentage         *Dec                  // the percentage of coins the contributors will get from each reward a provider get
	Shares                        uint64                // factor for bonus rewards at the end of the month (see rewards module)
    AllowedBlockLagForQosSync     int64                 // defines the accepted blocks a provider can be behind the chain without QOS degradation
	BlockLastUpdated              uint64                // the last block this spec was updated on chain
    ReliabilityThreshold          uint32                // this determines the probability of data reliability checks by the consumer
	DataReliabilityEnabled        bool                  // enables/disables data reliability for the chain
	BlockDistanceForFinalizedData uint32                              
	BlocksInFinalizationProof     uint32                              
}

Coin type is from Cosmos-SDK (cosmos.base.v1beta1.Coin). Dec type is from Cosmos-SDK math (cosmossdk.io/math).

A Contributor is a member of the Lava community who can earn token commissions by maintaining specs on Lava.

ApiCollection

ApiCollection is a struct that defines an interface, such as REST, JSON, etc., along with all of its APIs and properties.

type ApiCollection struct {
	Enabled         bool                // enables/disables the collection
	CollectionData  CollectionData      // defines the properties of the collection, also acts as a unique key
	Apis            []*Api              // list of api's in the collection
	Headers         []*Header           // list of headers supported by the interface and their behaviour
	InheritanceApis []*CollectionData   // list of other ApiCollection to inherite from
	ParseDirectives []*ParseDirective   // list of parsing instructions of specific api's
	Extensions      []*Extension        // list of extensions that providers can support in addition to the basic behaviour (for example, archive node)
	Verifications   []*Verification     // list of verifications that providers must pass to make sure they provide full functionality
}
CollectionData

CollectionData defines the api properties and acts as a unique key for the api collection.

type CollectionData struct {
	ApiInterface string         // defines the connection interface (rest/json/grpc etc...)
	InternalPath string         // defines internal path of the node for this specific ApiCollection
	Type         string         // type of api (POST/GET)
	AddOn        string         // optional APIs support
}

The ApiInterface field defines the API interface on which the limitations are applied. The available API interfaces for a chain are defined in the chain's spec. Overall, the API interfaces can be: jsonrpc, rest, tendermintrpc and grpc.

The InternalPath field is utilized for chains that have varying RPC API sets in different internal paths. Avalanche is a prime example of such a chain, consisting of three distinct subchains (or subnets) designed for different applications. For instance, Avalanche's C-Chain is dedicated to smart contracts, while Avalanche's X-Chain facilitates the sending and receiving of funds. For further information on how to define this field, please consult the Avalanche (AVAX) specification.

The Type field lets the user define APIs that have different functionalities depending on their type. the valid types are: GET and POST. An example of such API is Cosmos' /cosmos/tx/v1beta1/txs API. If it's sent as a GET request, it fetches transactions by event and if it's sent as a POST request, it sends a transaction.

The AddOn field lets you use additional optional APIs like debug, trace etc.

Extension

this field defines an extension for the api collection.

type Extension struct {
	Name         string  // name of the extension (archive)
	CuMultiplier float32 // cu factor for supporting this extension
	Rule         *Rule   // describes the rules when this extension is active
}
Api

Api define a specific api in the api collection.

type Api struct {
	Enabled           bool          // enable/disable the api
	Name              string        // api name
	ComputeUnits      uint64        // the amount of cu of this api (can be defined as the "price" of using this api)
	ExtraComputeUnits uint64        // not used
	Category          SpecCategory  // defines the property of the api
	BlockParsing      BlockParser   // specify how to parse the block from the api request
	TimeoutMs         uint64        // specifies the timeout expected for the api (mseconds)
}

example of an api definition:

    {
        "name": "eth_getBlockByNumber",
        "block_parsing": {
            "parser_arg": [
                "0"
            ],
            "parser_func": "PARSE_BY_ARG"
        },
        "compute_units": 20,
        "enabled": true,
        "category": {
            "deterministic": true,
            "local": false,
            "subscription": false,
            "stateful": 0
        },
        "extra_compute_units": 0
    },
SpecCategory

This struct defines properties of an api.

type SpecCategory struct {
	Deterministic bool   // if this api have the same response across nodes
	Local         bool   // TBD
	Subscription  bool   // subscription base api
	Stateful      uint32 // TBD
	HangingApi    bool   // marks this api with longer timeout
}
BlockParsing

This struct defines how to extract the block number from the api request.

type BlockParser struct {
	ParserArg    []string    // describes where is the block number in the request
	ParserFunc   PARSER_FUNC // how to parse the request
	DefaultValue string      // the expected default value
	Encoding     string      // number encoding (base64|Hex)
}

ParserFunc instructs how to parse the request to fetch the block number.

const (
	PARSER_FUNC_EMPTY                       PARSER_FUNC = 0 
	PARSER_FUNC_PARSE_BY_ARG                PARSER_FUNC = 1 
	PARSER_FUNC_PARSE_CANONICAL             PARSER_FUNC = 2 
	PARSER_FUNC_PARSE_DICTIONARY            PARSER_FUNC = 3 
	PARSER_FUNC_PARSE_DICTIONARY_OR_ORDERED PARSER_FUNC = 4
	PARSER_FUNC_DEFAULT PARSER_FUNC = 6
)
ParseDirective

ParseDirective is a struct that defines for the provider in a generic way how to fetch specific data from the node (for example: latest block height, block hash, ctv...). it describes for the api collection how to get information from the node.

type ParseDirective struct {
	FunctionTag      FUNCTION_TAG // defines what the function this serves for
	FunctionTemplate string       // api template to fill and send to the node
	ResultParsing    BlockParser  // description for parsing the result of the api
	ApiName          string       // the api name
}

FunctionTag can be one of the following :

const (
	FUNCTION_TAG_GET_BLOCKNUM           FUNCTION_TAG = 1 // get latest block number
	FUNCTION_TAG_GET_BLOCK_BY_NUM       FUNCTION_TAG = 2 // get a specific block by block number
	FUNCTION_TAG_SET_LATEST_IN_METADATA FUNCTION_TAG = 3
	FUNCTION_TAG_SET_LATEST_IN_BODY     FUNCTION_TAG = 4
	FUNCTION_TAG_VERIFICATION           FUNCTION_TAG = 5
)
Verification

The Verification struct defines how to verify a specific property of the API collection. For example, it can be used to verify the chain ID of the node.

type Verification struct {
	Name           string                               // verification name
	ParseDirective *ParseDirective                      // ParseDirective to get the the value to verify from the node
	Values         []*ParseValue                        // expected value we want from the result
	Severity       Verification_VerificationSeverity    // instructions for what to do if a verification fails
}
Headers

This struct defines for the provider what action to take on the headers of the relayed message.

type Header struct {
	Name        string              // name of the header
	Kind        Header_HeaderType   // what action to take
	FunctionTag FUNCTION_TAG        // what is the function of the header
}
Import

Specs can import from other specs, which allows for easy creation and maintenance of specs. Specs import the api collections of the base specs.

A good example of this is the cosmos base specs. All cosmos chains support queries/transactions of the bank module, and these are defined in a cosmos spec (which is disabled since it is a base spec). When creating a cosmos based spec, we can import the cosmos spec and obtain all the APIs of the bank module. This means that specs only need to define the APIs that are unique to the new chain.

Rules:

  • Import cycles of specs are prohibited.
  • Specs can override/disable/add APIs from the imported API collection.
  • Specs also import the verifications, which can be overridden when necessary (for example, the chain-id value must be overwritten).

Parameters

The Spec module does not contain parameters.

Queries

The Spec module supports the following queries:

Query Arguments What it does
list-spec none shows all the specs
params none show the params of the module
show-all-chains none shows all the specs with minimal info
show-chain-info chainid shows a spec with minimal info
show-spec chainid shows a full spec

Transactions

The Spec module does not support any transactions.

Proposals

The Spec module provides a proposal to add/overwrite a spec to the chain

lavad tx gov submit-legacy-proposal spec-add <spec_json_1>,<spec_json_2> --from alice <gas-flags>

A valid add_spec_json_1 JSON proposal format:

{
    "proposal": {
        "title": "Add Specs: Lava",
        "description": "Adding new specification support for relaying Lava data on Lava",
        "specs": [
            {
                "index": "LAV1",
                "name": "lava testnet",
                "enabled": true,
                "imports": [
                    "COSMOSSDK"
                ],
                "providers_types": 1,
                "reliability_threshold": 268435455,
                "data_reliability_enabled": true,
                "block_distance_for_finalized_data": 0,
                "blocks_in_finalization_proof": 1,
                "average_block_time": 30000,
                "allowed_block_lag_for_qos_sync": 2,
                                "shares" : 1,
                "min_stake_provider": {
                    "denom": "ulava",
                    "amount": "50000000000"
                },
                "api_collections": [
                    {
                        "enabled": true,
                        "collection_data": {
                            "api_interface": "rest",
                            "internal_path": "",
                            "type": "GET",
                            "add_on": ""
                        },
                        "apis": [
                            {
                                "name": "/lavanet/lava/spec/show_all_chains",
                                "block_parsing": {
                                    "parser_arg": [
                                        "latest"
                                    ],
                                    "parser_func": "DEFAULT"
                                },
                                "compute_units": 10,
                                "enabled": true,
                                "category": {
                                    "deterministic": true,
                                    "local": false,
                                    "subscription": false,
                                    "stateful": 0
                                },
                                "extra_compute_units": 0
                            }
                        ],
                        "headers": [],
                        "inheritance_apis": [],
                        "parse_directives": [],
                        "verifications": [
                            {
                                "name": "chain-id",
                                "values": [
                                    {
                                        "expected_value": "lava-testnet"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "deposit": "10000000ulava"
}
Events

The plans module has the following events:

Event When it happens
spec_add a successful addition of a spec
spec_modify a successful modification of an existing spec
spec_refresh a spec was rereshed since it had a imported spec modified

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExportGenesis 

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

ExportGenesis returns the capability module's exported genesis.

func HandleParameterChangeProposal 

func HandleParameterChangeProposal(ctx sdk.Context, k paramkeeper.Keeper, p *paramproposal.ParameterChangeProposal) error

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(k keeper.Keeper) sdk.Handler

NewHandler ...

func NewParamChangeProposalHandler 

func NewParamChangeProposalHandler(k paramkeeper.Keeper) v1beta1.Handler

overwriting the params handler so we can add events and callbacks on specific params NewParamChangeProposalHandler creates a new governance Handler for a ParamChangeProposal

func NewSpecProposalsHandler 

func NewSpecProposalsHandler(k keeper.Keeper) v1beta1.Handler

NewSpecProposalsHandler creates a new governance Handler for a Spec

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,
	accountKeeper types.AccountKeeper,
	bankKeeper types.BankKeeper,
) AppModule

func (AppModule) BeginBlock 

func (am AppModule) BeginBlock(ctx 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(_ 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) GenerateGenesisState 

func (AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState creates a randomized GenState of the module

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) Name 

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) ProposalContents 

func (AppModule) ProposalContents(_ module.SimulationState) []simtypes.WeightedProposalMsg

ProposalContents doesn't return any content functions for governance proposals

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) RegisterStoreDecoder 

func (am AppModule) RegisterStoreDecoder(_ sdk.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder

func (AppModule) WeightedOperations 

func (am AppModule) WeightedOperations(simState module.SimulationState) []simtypes.WeightedOperation

WeightedOperations returns the all the gov module operations with their respective weights.

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(clientCtx client.Context, mux *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(clientCtx client.Context, rtr *mux.Router)

RegisterRESTRoutes registers the capability module's REST service handlers.

func (AppModuleBasic) ValidateGenesis 

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

ValidateGenesis performs genesis state validation for the capability module.

Source Files

View all Source files

Directories

Path Synopsis
cli
utils
Package types is a reverse proxy.
 Package types is a reverse proxy.
migrations/v1

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.