From 137c758d5792838b9f62749d1a545d07d8bf44f6 Mon Sep 17 00:00:00 2001
From: Facundo Medica <14063057+facundomedica@users.noreply.github.com>
Date: Wed, 11 May 2022 08:23:54 -0300
Subject: [PATCH] chore: Add x/capability docs (#11922)

* chore: Add x/capability docs

* bad ident
---
 x/capability/spec/01_concepts.md |  1 +
 x/capability/spec/02_state.md    | 21 ++++++++++++++++++---
 x/capability/spec/README.md      | 13 +++++++------
 x/capability/types/keys.go       |  2 +-
 4 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/x/capability/spec/01_concepts.md b/x/capability/spec/01_concepts.md
index bb236a21ea86..93ecb6354ac7 100644
--- a/x/capability/spec/01_concepts.md
+++ b/x/capability/spec/01_concepts.md
@@ -32,3 +32,4 @@ not own.
 ## Stores
 
 * MemStore
+* KeyStore
diff --git a/x/capability/spec/02_state.md b/x/capability/spec/02_state.md
index b93de4bf4ab7..3ab713bdb90d 100644
--- a/x/capability/spec/02_state.md
+++ b/x/capability/spec/02_state.md
@@ -3,9 +3,24 @@ order: 2
 -->
 
 # State
+## In persisted KV store
 
-## Index
+1. Global unique capability index
+2. Capability owners
 
-## CapabilityOwners
+Indexes:
 
-## Capability
+* 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)`
diff --git a/x/capability/spec/README.md b/x/capability/spec/README.md
index ec612ba97697..db5289df5bc2 100644
--- a/x/capability/spec/README.md
+++ b/x/capability/spec/README.md
@@ -53,18 +53,19 @@ func NewApp(...) *App {
 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 initialized and sealed to populate the in-memory
-state and to prevent further scoped keepers from being created.
+main capability keeper must be sealed to prevent further scoped keepers from
+being created.
 
 ```go
 func NewApp(...) *App {
   // ...
 
-  // Initialize and seal the capability keeper so all persistent capabilities
-  // are loaded in-memory and prevent any further modules from creating scoped
+  // Creating a scoped keeper
+  scopedIBCKeeper := app.CapabilityKeeper.ScopeToModule(ibchost.ModuleName)
+
+  // Seal the capability keeper to prevent any further modules from creating scoped
   // sub-keepers.
-  ctx := app.BaseApp.NewContext(true, tmproto.Header{})
-  app.capabilityKeeper.InitializeAndSeal(ctx)
+  app.capabilityKeeper.Seal()
 
   return app
 }
diff --git a/x/capability/types/keys.go b/x/capability/types/keys.go
index 27661135824c..eccfba00a55f 100644
--- a/x/capability/types/keys.go
+++ b/x/capability/types/keys.go
@@ -23,7 +23,7 @@ var (
 	KeyIndex = []byte("index")
 
 	// KeyPrefixIndexCapability defines a key prefix that stores index to capability
-	// name mappings.
+	// owners mappings.
 	KeyPrefixIndexCapability = []byte("capability_index")
 
 	// KeyMemInitialized defines the key that stores the initialized flag in the memory store