capability

README

---

sidebar_position: 1

x/capability

Overview

x/capability is an implementation of a Cosmos SDK module, per ADR 003, that allows for provisioning, tracking, and authenticating multi-owner capabilities at runtime.

The keeper maintains two states: persistent and ephemeral in-memory. The persistent store maintains a globally unique auto-incrementing index and a mapping from capability index to a set of capability owners that are defined as a module and capability name tuple. The in-memory ephemeral state keeps track of the actual capabilities, represented as addresses in local memory, with both forward and reverse indexes. The forward index maps module name and capability tuples to the capability name. The reverse index maps between the module and capability name and the capability itself.

The keeper allows the creation of "scoped" sub-keepers which are tied to a particular module by name. Scoped keepers must be created at application initialization and passed to modules, which can then use them to claim capabilities they receive and retrieve capabilities which they own by name, in addition to creating new capabilities & authenticating capabilities passed by other modules. A scoped keeper cannot escape its scope, so a module cannot interfere with or inspect capabilities owned by other modules.

The keeper provides no other core functionality that can be found in other modules like queriers, REST and CLI handlers, and genesis state.

Initialization

During application initialization, the keeper must be instantiated with a persistent store key and an in-memory store key.

type App struct {
  // ...

  capabilityKeeper *capability.Keeper
}

func NewApp(...) *App {
  // ...

  app.capabilityKeeper = capability.NewKeeper(codec, persistentStoreKey, memStoreKey)
}

After the keeper is created, it can be used to create scoped sub-keepers which are passed to other modules that can create, authenticate, and claim capabilities. After all the necessary scoped keepers are created and the state is loaded, the main capability keeper must be sealed to prevent further scoped keepers from being created.

func NewApp(...) *App {
  // ...

  // Creating a scoped keeper
  scopedIBCKeeper := app.CapabilityKeeper.ScopeToModule(ibchost.ModuleName)

  // Seal the capability keeper to prevent any further modules from creating scoped
  // sub-keepers.
  app.capabilityKeeper.Seal()

  return app
}

Contents

• Concepts
  • Capabilities
  • Stores
• State
  • In persisted KV store
  • In-memory KV store

Concepts

Capabilities

Capabilities are multi-owner. A scoped keeper can create a capability via NewCapability which creates a new unique, unforgeable object-capability reference. The newly created capability is automatically persisted; the calling module need not call ClaimCapability. Calling NewCapability will create the capability with the calling module and name as a tuple to be treated the capabilities first owner.

Capabilities can be claimed by other modules which add them as owners. ClaimCapability allows a module to claim a capability key which it has received from another module so that future GetCapability calls will succeed. ClaimCapability MUST be called if a module which receives a capability wishes to access it by name in the future. Again, capabilities are multi-owner, so if multiple modules have a single Capability reference, they will all own it. If a module receives a capability from another module but does not call ClaimCapability, it may use it in the executing transaction but will not be able to access it afterwards.

AuthenticateCapability can be called by any module to check that a capability does in fact correspond to a particular name (the name can be un-trusted user input) with which the calling module previously associated it.

GetCapability allows a module to fetch a capability which it has previously claimed by name. The module is not allowed to retrieve capabilities which it does not own.

Stores

• MemStore
• KeyStore

State

In persisted KV store

1. Global unique capability index
2. Capability owners

Indexes:

• Unique index: []byte("index") -> []byte(currentGlobalIndex)
• Capability Index: []byte("capability_index") | []byte(index) -> ProtocolBuffer(CapabilityOwners)

In-memory KV store

1. Initialized flag
2. Mapping between the module and capability tuple and the capability name
3. Mapping between the module and capability name and its index

Indexes:

• Initialized flag: []byte("mem_initialized")
• RevCapabilityKey: []byte(moduleName + "/rev/" + capabilityName) -> []byte(index)
• FwdCapabilityKey: []byte(moduleName + "/fwd/" + capabilityPointerAddress) -> []byte(capabilityName)

Documentation

Index

• func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState
• func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState)
• type AppModule
  • func NewAppModule(cdc codec.Codec, keeper keeper.Keeper, sealKeeper bool) AppModule
  • func (am AppModule) BeginBlock(ctx sdk.Context, _ abci.RequestBeginBlock)
  • func (AppModule) ConsensusVersion() uint64
  • func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage
  • func (AppModule) GenerateGenesisState(simState *module.SimulationState)
  • func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate
  • func (am AppModule) IsAppModule()
  • func (am AppModule) IsOnePerModuleType()
  • func (am AppModule) Name() string
  • func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)
  • func (am AppModule) RegisterServices(module.Configurator)
  • func (am AppModule) RegisterStoreDecoder(sdr sdk.StoreDecoderRegistry)
  • func (am AppModule) WeightedOperations(simState module.SimulationState) []simtypes.WeightedOperation
• type AppModuleBasic
  • func NewAppModuleBasic(cdc codec.Codec) AppModuleBasic
  • func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage
  • func (AppModuleBasic) GetQueryCmd() *cobra.Command
  • func (a AppModuleBasic) GetTxCmd() *cobra.Command
  • func (AppModuleBasic) Name() string
  • func (a AppModuleBasic) RegisterGRPCGatewayRoutes(_ client.Context, _ *gwruntime.ServeMux)
  • func (a AppModuleBasic) RegisterInterfaces(_ cdctypes.InterfaceRegistry)
  • func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)
  • func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error
• type CapabilityInputs
• type CapabilityOutputs
  • func ProvideModule(in CapabilityInputs) CapabilityOutputs

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.

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, sealKeeper bool) AppModule

func (AppModule) BeginBlock

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

BeginBlock executes all ABCI BeginBlock logic respective to the capability module. BeginBlocker calls InitMemStore to assert that the memory store is initialized. It's safe to run multiple times.

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements AppModule/ConsensusVersion.

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 capability 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) IsAppModule

func (am AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType

func (am AppModule) IsOnePerModuleType()

IsOnePerModuleType implements the depinject.OnePerModuleType interface.

func (AppModule) Name

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) RegisterInvariants

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

RegisterInvariants registers the capability module's invariants.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(module.Configurator)

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

func (AppModule) RegisterStoreDecoder

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

RegisterStoreDecoder registers a decoder for capability module's types

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.Codec) 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) RegisterGRPCGatewayRoutes

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

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the capability module.

func (AppModuleBasic) RegisterInterfaces

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

RegisterInterfaces registers the module's interface types

func (AppModuleBasic) RegisterLegacyAminoCodec

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

RegisterLegacyAminoCodec does nothing. Capability does not support amino.

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.

type CapabilityInputs

type CapabilityInputs struct {
	depinject.In

	Config *modulev1.Module

	KvStoreKey  *store.KVStoreKey
	MemStoreKey *store.MemoryStoreKey
	Cdc         codec.Codec
}

type CapabilityOutputs

type CapabilityOutputs struct {
	depinject.Out

	CapabilityKeeper *keeper.Keeper
	Module           appmodule.AppModule
}

func ProvideModule

func ProvideModule(in CapabilityInputs) CapabilityOutputs