projects

package
v3.1.9-experimental Latest Latest
Warning

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

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

README

x/projects

Abstract

This document specifies the projects module of Lava Protocol.

The projects module is responsible for managing Lava's consumer projects. When a consumer wants to use Lava, they need to purchase a subscription. Within the subscription, consumers can create projects to utilize Lava and make RPC calls seamlessly.

Note that the plans module is closely connected to the subscription and projects modules. To fully understand how subscriptions, plans, and projects work together, please also refer to their respective READMEs.

Contents

Concepts

Project

Once a consumer purchases a subscription, they can create projects under it. Each project has a unique name (index) within this subscription. A project is defined as follows:

type Project struct {
	Index               string        // project unique index
	Subscription        string        // project associated subscription
	Enabled             bool          // project enabled/disabled
	ProjectKeys         []ProjectKey  // list of project keys
	AdminPolicy         Policy        // project admin policy
	UsedCu              uint64        // project used compute units (CU) per month
	SubscriptionPolicy  Policy        // project subscription policy
	Snapshot            uint64        // project snapshot unique index
}

The project index is: <subscription_owner_address>-<project_name> (for example: lava@1p7ezdua4ma90858h7zy9727wmqy53vk0mkdlvg-myProject). When a consumer buys a subscription, an admin project is automatically generated with the index <subscription_owner_address>-admin.

The project is subject to three types of policies: the plan's policy, the subscription's policy, and the admin policy. The plan's policy cannot be changed using transactions (only via a government proposal), while the other two policies can be changed using transactions. The effective policy that the project is subject to is the strictest policy calculated from all three policies. To query for the project's effective policy, use the Pairing module's query: effective-policy (see below). Note that the subscription policy refers to the policy applied the subscription owner, while the admin policy is the policy defined by the project's admins. Also, both policies can be modified using the project module's transactions. The changes apply on the next epoch.

Projects are saved in a fixation store (see FixationStore module for reference). By using the snapshot ID, we can differentiate between different versions of the project.

For more details regarding the Policy struct and its limitations, see here. For more details about ProjectKeys, see below.

Project Keys

A project has a list of accounts (project keys) that can use the project in different ways. There are two kinds of keys: admin key and developer key. A project key is defined as follows:

type ProjectKey struct {
	Key    string  // user lava address
	Kinds  uint32  // key kind
}

The Kinds enum is defined as follows:

enum Kinds {
    ADMIN = 1            // admin key
    DEVELOPER = 2        // developer key
    ADMIN+DEVELOPER = 3  // admin+developer key
}

The admin key lets the admin edit the project's admin policy, enable/disable the project and add/delete other project keys. A single user can be admin in multiple projects. The subscription owner is automatically considered an admin in all of the projects created under it.

The developer key lets a user to use the project, i.e., make RPC calls and use the project's CU. A single user (consumer) can only be a developer in one project. The project's developer can be viewed as a dapp developer that wants to use Lava to get RPC data for their dapp. To allow end users use their project to get RPC data, the dapp developer will need to use badges. For more details on badges, see below.

Note that the admin cannot use the project's CU like a developer, they can only edit the project's properties.

The project keys can be added/modified using the project module's transactions. The changes apply on the next epoch.

Badges

Badges are a method to grant compute units (CU) from projects to other users. Given a subscription with projects, a developer key (in a project) can be used to generate a badge key, to be signed by an external badge-server. The badge is ephemeral, limited in time and in CU capacity; End users, who are not the original developers of the project, can use the badge to pair with providers on behalf of the developer key. The requests made by end users using the badge will be charged to the corresponding project after verification.

A badge is defined as follows:

type Badge struct {
	CuAllocation  uint64  // badge CU limit
	Epoch         uint64  // badge epoch
	Address       string  // badge user address
	LavaChainId   string  // lava chain ID (testnet/mainnet)
	ProjectSig    []byte  // developer key signature (for verification)
	VirtualEpoch  uint64  // used for emergency mode
}

The badge's Epoch field is the epoch in which the badge is valid in. When the epoch changes, the badge becomes invalid. The badge's VirtualEpoch is used in emergency mode (see Downtime module's README for more details).

When a badge user sends a relay request to the provider, the first request must be accompanied by the signed message (proof of grant, i.e., a valid ProjectSig which should be the developer key's signature). Subsequent relays from the same badge don't have to add a valid ProjectSig.

Parameters

The projects module does not contain parameters.

Queries

The projects module supports the following queries:

Query Arguments What it does
info index (string) shows a project's info by index
developer developer address (string) show a project's info by developer address (registered with a developer key)
params none shows the module's parameters

More projects related queries from other modules:

Query (module) Arguments What it does
effective-policy (Pairing) spec-id (string), developer/index (string) shows a project's effective policy by project index/developer address and spec index

The spec index argument can be obtained using the Spec module's show-all-chains query.

Transactions

All the transactions below require setting the --from flag and gas related flags. Also, all state changes from these transactions are applied on the start of the next epoch.

The projects module supports the following transactions:

Transaction Arguments What it does
set-policy index (string), policy file path (string) sets the admin policy of a project by index (must be sent from the admin/subscription owner)
set-subscription-policy indices ([]string), policy file path sets the subscription policy of the subscription's projects by their index (must be sent from the subscription owner)
add-keys index (string), project keys file path (string) adds a project key to a project by index
del-keys index (string), project keys file path (string) deletes a project key from a project by index

Note that the add-keys and del-keys transactions also support key management with flags, in addition to file input. Refer to the help section of the commands for more details.

To get more details about the policy and project keys YAML file format, see below.

Project Policy YAML

Both the set-policy and set-subscription-policy transactions use the same policy YAML format.

Example of a policy YAML file:

Policy:
  geolocation_profile: 1  # USC
  total_cu_limit: 10000
  epoch_cu_limit: 100
  max_providers_to_pair: 7
  selected_providers_mode: ALLOWED
  chain_policies:
    - chain_id: ETH1
      requirements:
        - collection:
            api_interface: "YAMLrpc"
            type: "POST"
            add_on: "debug"
    - chain_id: EVMOS
      requirements:
        - collection:
            api_interface: "YAMLrpc"
            type: "POST"
          extensions:
            - "archive"
          mixed: true
        - collection:
            api_interface: "rest"
            type: "GET"
          extensions:
            - "archive"
          mixed: true
        - collection:
            api_interface: "grpc"
            type: ""
          extensions:
            - "archive"
          mixed: true
        - collection:
            api_interface: "tendermintrpc"
            type: ""
          extensions:
            - "archive"
          mixed: true
    - chain_id: "*" # allows all other chains without specifying

All fields are optional. An unfilled field will be replaced with a default value or be ignored.

Project Keys YAML

Both the add-keys and del-keys transactions use the same project key YAML format.

Example of a project key YAML file:

Project-Keys:
  - key: "lava@1xtfqykth53pkt97v955h3lql8zkj2m4s4rq9cr"
    Kinds: 3
  - key: "lava@1r3ernqu6rzp95z92580wae7xpuqwmznk3eqd7w"
    Kinds: 1

All fields are mandatory.

Proposals

The projects module does not support any proposals.

Events

The projects module has the following events:

Event When it happens
add_key_to_project_event a successful addition of a project key
del_key_from_project_event a successful deletion of a project key
set_admin_policy_event a successful set of project's admin policy
set_subscription_policy_event a successful set of project's subscription policy

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

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(_ 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. It also registers migration handlers.

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
client
cli
migrations
v2
v3
v4
v5
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.