github.com/Finschia/finschia-sdk@v0.48.1/x/capability/spec/README.md (about)

     1  <!--
     2  order: 0
     3  title: Capability Overview
     4  parent:
     5    title: "capability"
     6  -->
     7  
     8  # `capability`
     9  
    10  ## Overview
    11  
    12  `x/capability` is an implementation of a Cosmos SDK module, per [ADR 003](./../../../docs/architecture/adr-003-dynamic-capability-store.md),
    13  that allows for provisioning, tracking, and authenticating multi-owner capabilities
    14  at runtime.
    15  
    16  The keeper maintains two states: persistent and ephemeral in-memory. The persistent
    17  store maintains a globally unique auto-incrementing index and a mapping from
    18  capability index to a set of capability owners that are defined as a module and
    19  capability name tuple. The in-memory ephemeral state keeps track of the actual
    20  capabilities, represented as addresses in local memory, with both forward and reverse indexes.
    21  The forward index maps module name and capability tuples to the capability name. The
    22  reverse index maps between the module and capability name and the capability itself.
    23  
    24  The keeper allows the creation of "scoped" sub-keepers which are tied to a particular
    25  module by name. Scoped keepers must be created at application initialization and
    26  passed to modules, which can then use them to claim capabilities they receive and
    27  retrieve capabilities which they own by name, in addition to creating new capabilities
    28  & authenticating capabilities passed by other modules. A scoped keeper cannot escape its scope,
    29  so a module cannot interfere with or inspect capabilities owned by other modules.
    30  
    31  The keeper provides no other core functionality that can be found in other modules
    32  like queriers, REST and CLI handlers, and genesis state.
    33  
    34  ## Initialization
    35  
    36  During application initialization, the keeper must be instantiated with a persistent
    37  store key and an in-memory store key.
    38  
    39  ```go
    40  type App struct {
    41    // ...
    42  
    43    capabilityKeeper *capability.Keeper
    44  }
    45  
    46  func NewApp(...) *App {
    47    // ...
    48  
    49    app.capabilityKeeper = capability.NewKeeper(codec, persistentStoreKey, memStoreKey)
    50  }
    51  ```
    52  
    53  After the keeper is created, it can be used to create scoped sub-keepers which
    54  are passed to other modules that can create, authenticate, and claim capabilities.
    55  After all the necessary scoped keepers are created and the state is loaded, the
    56  main capability keeper must be initialized and sealed to populate the in-memory
    57  state and to prevent further scoped keepers from being created.
    58  
    59  ```go
    60  func NewApp(...) *App {
    61    // ...
    62  
    63    // Initialize and seal the capability keeper so all persistent capabilities
    64    // are loaded in-memory and prevent any further modules from creating scoped
    65    // sub-keepers.
    66    ctx := app.BaseApp.NewContext(true, ocproto.Header{})
    67    app.capabilityKeeper.InitializeAndSeal(ctx)
    68  
    69    return app
    70  }
    71  ```
    72  
    73  ## Contents
    74  
    75  1. **[Concepts](01_concepts.md)**
    76  1. **[State](02_state.md)**