Cosmos SDK 动态能力存储(Dynamic Capability Store)设计解析:ADR-003 与对象能力模型
Cosmos SDK 动态能力存储(Dynamic Capability Store)设计解析:ADR-003 与对象能力模型
导读
本文围绕 Cosmos SDK 仓库中的 ADR-003 动态能力存储 展开,系统讲解 SDK 为满足 IBC 规范而引入的 CapabilityKeeper 架构:如何在交易执行期(运行时)创建、跟踪与认证对象能力(object-capability)密钥,如何通过内存映射解决"能力指针无法持久化"的共识难题,以及模块间如何通过 ScopeToModule、ClaimCapability、AuthenticateCapability 等接口安全地传递与复用能力。读完本文,你将掌握这套能力模型的数据结构设计、各方法的调用语义与生命周期约束,并能在自己的模块中正确接入 Scoped Capability Keeper。
说明:本仓库当前版本已将
x/capability模块作为独立依赖交由 IBC 使用,本文以 ADR-003 原文为核心,结合仓库内的对象能力模型文档 Object-Capability Model、StoreKey/CapabilityKey 定义 及模块管理文档中的初始化顺序要求进行佐证。
背景:为什么状态机必须在运行时创建能力密钥
IBC 规范对动态能力的要求
IBC(Inter-Blockchain Communication)规范的完整实现,要求在运行时(即交易执行过程中)创建并认证对象能力密钥。按照 ICS-5(Port Allocation)技术规范,每当初始化一个新的 port 或 channel 时,都会为它创建能力密钥,用于后续对 port 或 channel 使用行为的认证。由于 channel、甚至 port 都可能在交易执行期间被初始化,状态机必须在这一时刻具备创建对象能力密钥的能力。
既有 StoreKey 体系的局限
在 ADR-003 提出之前,Cosmos SDK 不具备这种动态能力。原有的对象能力密钥本质上是 StoreKey 结构体的内存地址指针,这些 StoreKey 在 app.go 中于应用初始化阶段创建,并以固定参数形式传入各 Keeper。
从当前仓库源码可以看到这种"指针即能力"的设计被显式固化了下来:
// KVStoreKey is used for accessing substores.
// Only the pointer value should ever be used - it functions as a capabilities key.
type KVStoreKey struct {
name string
}
// NewKVStoreKey returns a new pointer to a KVStoreKey.
// Use a pointer so keys don't collide.
func NewKVStoreKey(name string) *KVStoreKey {
if name == "" {
panic("empty key name not allowed")
}
return &KVStoreKey{name: name}
}
上述代码位于 store/types/store.go,注释中明确写着"只有指针值应当被使用——它充当能力密钥"。同时,store/types/store.go 还定义了与 IBC 对象能力生成直接对应的别名类型:
// CapabilityKey represent the Cosmos SDK keys for object-capability
// generation in the IBC protocol as defined in ICS-005 port allocation
type CapabilityKey StoreKey
这套指针体系存在的根本问题是:Keeper 无法在交易执行期间创建或保存能力密钥。虽然 Keeper 可以调用 NewKVStoreKey 并取返回结构体的内存地址,但若把这个地址写进 Merklised store(默克尔化状态存储),就会引发共识故障(consensus fault)——因为同一份状态在不同机器上的内存地址必然不同。这种"不可预测性"恰恰是刻意的:如果能力密钥可以预测,它就无法充当对象能力了。
因此,Keeper 需要:
- 一个私有的、可在交易执行期间被修改的 store key 映射;
- 一套在应用每次启动/重启时重新生成这些唯一内存地址(能力密钥)的机制;
- 一种在交易失败时回滚能力创建操作的机制。
ADR-003 正是针对这些需求提出了完整的接口与机制设计。
决策:引入 CapabilityKeeper 抽象
ADR-003 的核心决策是:Cosmos SDK 将新增一个 CapabilityKeeper 抽象,负责在运行时**供给(provision)、跟踪(track)与认证(authenticate)**能力。
在 app.go 的应用初始化阶段,CapabilityKeeper 通过 ScopeToModule(见下文)为各模块建立唯一的函数引用,从而在后续被调用时能够识别出是哪个模块在发起调用。
当初始状态从磁盘加载时,CapabilityKeeper 的 Initialise 函数会为所有此前分配过的能力标识符(在历史交易执行期间分配并归属到特定模块)创建新的能力密钥,并在链运行期间将它们保存在纯内存 store 中。
数据结构设计:三层存储与两向映射
CapabilityKeeper 包含一个持久化 KVStore、一个 MemoryStore 以及一个内存中的 go map,各司其职:
| 存储 | 作用 |
|---|---|
持久化 KVStore |
记录哪个能力归属于哪些模块(owner 集合) |
MemoryStore |
保存两层映射:正向映射(模块名 + 能力 → 能力名)与反向映射(模块名 + 能力名 → 能力索引) |
内存 go map(capMap) |
以索引为键,保存能力指针本身,保证每次取回的都是同一内存地址 |
这里的关键设计动机是:能力无法被直接 marshal 进 KVStore 再 unmarshal 取出——那会改变能力的内存位置,从而破坏"指针即能力"的语义。因此 KVStore 中的反向映射只映射到一个索引(index),这个索引再作为键去查询临时 go map,最终拿到处于原始内存位置的能力对象。
Capability:带全局唯一索引的结构体
Capability 与 StoreKey 类似,但它拥有的不是名字,而是一个全局唯一的 Index()。同时提供 String() 方法用于调试。能力本质上就是一个结构体,取其地址作为实际的能力引用:
type Capability struct {
index uint64
}
CapabilityKeeper 与 ScopedCapabilityKeeper
CapabilityKeeper 持有持久化 store key、内存 store key,以及已分配模块名的映射:
type CapabilityKeeper struct {
persistentKey StoreKey
memKey StoreKey
capMap map[uint64]*Capability
moduleNames map[string]interface{}
sealed bool
}
CapabilityKeeper 的核心能力是创建作用域化(scoped)子 Keeper,每个子 Keeper 绑定到一个特定的模块名。这些 ScopedCapabilityKeeper 必须在应用初始化阶段创建并传给各模块。模块拿到后可以:
- 认领(claim)它们收到的能力;
- 按名字检索(get)自己拥有的能力;
- 创建新能力;
- 认证其他模块传递过来的能力。
type ScopedCapabilityKeeper struct {
persistentKey StoreKey
memKey StoreKey
capMap map[uint64]*Capability
moduleName string
}
生命周期方法:从 Scope 到 Seal
ScopeToModule:创建唯一命名的 scoped keeper
ScopeToModule 用于创建指定名字的 scoped 子 keeper,模块名必须唯一,且必须在 InitialiseAndSeal 之前调用:
func (ck CapabilityKeeper) ScopeToModule(moduleName string) ScopedCapabilityKeeper {
if k.sealed {
panic("cannot scope to module via a sealed capability keeper")
}
if _, ok := k.scopedModules[moduleName]; ok {
panic(fmt.Sprintf("cannot create multiple scoped keepers for the same module name: %s", moduleName))
}
k.scopedModules[moduleName] = struct{}{}
return ScopedKeeper{
cdc: k.cdc,
storeKey: k.storeKey,
memKey: k.memKey,
capMap: k.capMap,
module: moduleName,
}
}
注意两个防御性细节:sealed 标记会阻止在封印后继续创建 scoped keeper(直接 panic);同名的重复 scoped keeper 也会被 panic 拒绝。
InitialiseAndSeal:恢复能力映射并封印
InitialiseAndSeal 必须且只能被调用一次,时机是在加载完初始状态、创建好所有必要的 ScopedCapabilityKeeper 之后。它负责:
- 按各模块此前认领过的密钥,用新创建的能力密钥填充内存 store;
- 阻止任何新的
ScopedCapabilityKeeper被创建。
func (ck CapabilityKeeper) InitialiseAndSeal(ctx Context) {
if ck.sealed {
panic("capability keeper is sealed")
}
persistentStore := ctx.KVStore(ck.persistentKey)
map := ctx.KVStore(ck.memKey)
// initialise memory store for all names in persistent store
for index, value := range persistentStore.Iter() {
capability = &CapabilityKey{index: index}
for moduleAndCapability := range value {
moduleName, capabilityName := moduleAndCapability.Split("/")
memStore.Set(moduleName + "/fwd/" + capability, capabilityName)
memStore.Set(moduleName + "/rev/" + capabilityName, index)
ck.capMap[index] = capability
}
}
ck.sealed = true
}
从代码可以看到,初始化时逐条读取持久化 store 中的 owner 记录,拆分出 模块名/能力名,同时写入正向映射(fwd/)、反向映射(rev/)以及内存索引映射 capMap,最后置 sealed = true。
NewCapability:创建不可伪造的唯一能力
任何模块都可以调用 NewCapability 创建新的、唯一且不可伪造的对象能力引用。新能力自动持久化,调用模块无需再调用 ClaimCapability:
func (sck ScopedCapabilityKeeper) NewCapability(ctx Context, name string) (Capability, error) {
// check name not taken in memory store
if capStore.Get("rev/" + name) != nil {
return nil, errors.New("name already taken")
}
// fetch the current index
index := persistentStore.Get("index")
// create a new capability
capability := &CapabilityKey{index: index}
// set persistent store
persistentStore.Set(index, Set.singleton(sck.moduleName + "/" + name))
// update the index
index++
persistentStore.Set("index", index)
// set forward mapping in memory store from capability to name
memStore.Set(sck.moduleName + "/fwd/" + capability, name)
// set reverse mapping in memory store from name to index
memStore.Set(sck.moduleName + "/rev/" + name, index)
// set the in-memory mapping from index to capability pointer
capMap[index] = capability
// return the newly created capability
return capability
}
该方法完整展示了三层存储的协作流程:先检查名字是否已被占用(基于反向映射),然后取当前自增索引、构造新能力、写持久化 owner 集合、更新索引计数器、写内存正向/反向映射、登记 capMap,最后返回能力对象。
认证与所有权管理:四大核心方法
AuthenticateCapability:校验能力与名字的对应关系
任何模块都可以调用 AuthenticateCapability,检查一个能力是否确实与某个名字对应——这个名字可以是不可信的用户输入——且该名字是由调用模块此前与之关联的:
func (sck ScopedCapabilityKeeper) AuthenticateCapability(name string, capability Capability) bool {
// return whether forward mapping in memory store matches name
return memStore.Get(sck.moduleName + "/fwd/" + capability) === name
}
实现基于内存 store 的正向映射做精确比对,逻辑非常简单且高效。
ClaimCapability:认领来自其他模块的能力
ClaimCapability 允许一个模块认领它从其他模块收到的能力密钥,使未来的 GetCapability 调用能够成功。关键语义:能力是**多所有者(multi-owner)**的——如果多个模块持有同一个 Capability 引用,它们将同时拥有它。因此,任何收到能力并希望将来按名字访问它的模块,必须调用 ClaimCapability:
func (sck ScopedCapabilityKeeper) ClaimCapability(ctx Context, capability Capability, name string) error {
persistentStore := ctx.KVStore(sck.persistentKey)
// set forward mapping in memory store from capability to name
memStore.Set(sck.moduleName + "/fwd/" + capability, name)
// set reverse mapping in memory store from name to capability
memStore.Set(sck.moduleName + "/rev/" + name, capability)
// update owner set in persistent store
owners := persistentStore.Get(capability.Index())
owners.add(sck.moduleName + "/" + name)
persistentStore.Set(capability.Index(), owners)
}
GetCapability:按名字取回自己拥有的能力
GetCapability 允许模块按名字取回其此前认领过的能力。模块不能检索它不拥有的能力:
func (sck ScopedCapabilityKeeper) GetCapability(ctx Context, name string) (Capability, error) {
// fetch the index of capability using reverse mapping in memstore
index := memStore.Get(sck.moduleName + "/rev/" + name)
// fetch capability from go-map using index
capability := capMap[index]
// return the capability
return capability
}
这段代码正是 ADR 中"反向映射 → 索引 → go map 指针"两层间接寻址的实际落地:先通过内存 store 的反向映射拿到索引,再用索引从 capMap 取回能力指针。这也是 ADR 承认的"额外一层间接"代价的由来。
ReleaseCapability:释放所有权
ReleaseCapability 允许模块释放其此前认领的能力。当不再有任何所有者时,该能力会被全局删除:
func (sck ScopedCapabilityKeeper) ReleaseCapability(ctx Context, capability Capability) err {
persistentStore := ctx.KVStore(sck.persistentKey)
name := capStore.Get(sck.moduleName + "/fwd/" + capability)
if name == nil {
return error("capability not owned by module")
}
// delete forward mapping in memory store
memoryStore.Delete(sck.moduleName + "/fwd/" + capability, name)
// delete reverse mapping in memory store
memoryStore.Delete(sck.moduleName + "/rev/" + name, capability)
// update owner set in persistent store
owners := persistentStore.Get(capability.Index())
owners.remove(sck.moduleName + "/" + name)
if owners.size() > 0 {
// there are still other owners, keep the capability around
persistentStore.Set(capability.Index(), owners)
} else {
// no more owners, delete the capability
persistentStore.Delete(capability.Index())
delete(capMap[capability.Index()])
}
}
注意其防御逻辑:如果正向映射中查不到名字,说明该模块并不拥有此能力,直接返回错误。释放时会同步清理内存 store 的正向/反向映射,并根据持久化 owner 集合是否为空决定保留能力还是全局删除(含 capMap 清理)。
接入模式:从初始化到跨模块能力流转
初始化模式
任何使用动态能力的模块,都必须在 app.go 中获得一个 ScopedCapabilityKeeper。标准流程如下:
ck := NewCapabilityKeeper(persistentKey, memoryKey)
mod1Keeper := NewMod1Keeper(ck.ScopeToModule("mod1"), ....)
mod2Keeper := NewMod2Keeper(ck.ScopeToModule("mod2"), ....)
// other initialisation logic ...
// load initial state...
ck.InitialiseAndSeal(initialContext)
要点:
NewCapabilityKeeper需要传入持久化 store key 与内存 store key 两个参数;- 每个模块通过
ck.ScopeToModule("模块名")获得专属的 scoped keeper,模块名必须全局唯一; - 所有 scope 操作都必须在加载初始状态之后、
ck.InitialiseAndSeal(initialContext)之前完成; InitialiseAndSeal恰好调用一次,此后 keeper 被封印。
这与仓库中 模块管理器文档 关于模块初始化顺序的要求相互印证:IBC 的 capability 模块应当先于所有其他模块完成初始化,以便它能先初始化好所有能力——这正对应 ADR 中"先 scope 全部模块、再 InitialiseAndSeal"的时序设计。
创建、传递、认领与使用能力
考虑如下典型场景:mod1 创建一个能力,将其按名字与某个资源(例如 IBC channel)关联,然后传给 mod2 供其后续使用。
模块 1 创建能力并传递:
capability := scopedCapabilityKeeper.NewCapability(ctx, "resourceABC")
mod2Keeper.SomeFunction(ctx, capability, args...)
模块 2 的 SomeFunction 认领该能力:
func (k Mod2Keeper) SomeFunction(ctx Context, capability Capability) {
k.sck.ClaimCapability(ctx, capability, "resourceABC")
// other logic...
}
稍后,模块 2 按名字取回能力并交还给模块 1,由模块 1 对照资源进行认证:
func (k Mod2Keeper) SomeOtherFunction(ctx Context, name string) {
capability := k.sck.GetCapability(ctx, name)
mod1.UseResource(ctx, capability, "resourceABC")
}
模块 1 在放行前校验该能力密钥已被认证可操作该资源:
func (k Mod1Keeper) UseResource(ctx Context, capability Capability, resource string) {
if !k.sck.AuthenticateCapability(name, capability) {
return errors.New("unauthenticated")
}
// do something with the resource
}
能力可继续传递:如果模块 2 把能力密钥再传给模块 3,模块 3 同样可以认领并像模块 2 那样调用模块 1。此时模块 1、模块 2、模块 3 三者都将拥有并使用这一能力——这正是 ClaimCapability"多所有者"语义的体现,也符合对象能力模型中"只有持有引用才能获得引用(Only connectivity begets connectivity)"的传递规则。
事务失败时的回滚语义
ADR-003 在积极影响中特别强调了这一点:CapabilityKeeper 允许从 go map 中返回同一个能力指针,同时在交易失败时回滚对持久化 KVStore 与内存 MemoryStore 的所有写入。
这是本设计正确性的关键支柱:由于能力指针保存在 capMap(内存 go map)中而非状态存储里,交易回滚不会触及这些指针本身;而状态层(KVStore / MemoryStore)的写入会随交易回滚一并撤销,从而保证失败交易不会留下"幽灵能力"或悬挂的所有权记录。
与对象能力模型的整体关系
ADR-003 并非孤立设计,它是 Cosmos SDK 整体对象能力安全模型的组成部分。仓库的 Object-Capability Model 文档阐述了这一模型的两条核心规则:
- 对象 A 只有持有对象 B 的引用时,才能向 B 发送消息;
- 对象 A 只有通过消息收到对象 C 的引用时,才能获得对 C 的引用。
由此推导出"只有连通性才能产生连通性"的结论,即对象只能通过预先存在的引用链获得其他对象的引用。在 00-overview.md 中,SDK 也被明确定位为"基于能力(capabilities-based)的系统,使开发者能更好地推理模块间交互的安全性"。
ADR-003 的动态能力存储正是把这两条规则落地为可执行的机制:NewCapability 创建不可伪造的唯一引用,ClaimCapability/GetCapability 控制引用的获得途径,AuthenticateCapability 在每次资源访问前进行引用校验——从而使模块间的安全边界不依赖全局信任,而是依赖对具体引用的持有。
影响评估与后续演进
积极影响
- 实现了动态能力支持,使 IBC 等场景可以在交易执行期间创建能力;
CapabilityKeeper能从 go map 中返回同一能力指针,同时保证交易失败时回滚持久化 KVStore 与内存 MemoryStore 的写入。
消极影响
- 需要额外引入一个 Keeper;
- 与既有
StoreKey体系存在部分重叠(未来可考虑合并,因为该设计在功能上是超集); - 反向映射需要额外一层间接:MemoryStore 必须映射到索引,索引再作为 go map 的键取回实际能力。
中性影响
- 暂无已知中性影响。
状态与演进
该 ADR 的初始状态为 Proposed(2019-12-12 初版,2020-04-02 修订内存存储部分)。此后该机制在 Cosmos SDK 生态中持续演进:x/capability 模块作为 IBC 能力的承载者被移出主仓库作为独立依赖,能力密钥的类型别名 CapabilityKey 与"指针即能力"的注释至今仍保留在 store/types/store.go 中,作为这套设计在核心类型层面的延续。模块初始化的时序要求(capability 模块必须先于其他模块初始化)也仍记录于 模块管理器文档,可见 ADR-003 确立的架构约束在实践中被完整继承。
结语
ADR-003 通过"持久化 KVStore 记所有权 + MemoryStore 存双映射 + go map 保指针"的三层设计,优雅地解决了"能力指针无法持久化"这一共识层面的根本矛盾,为 IBC 乃至整个 Cosmos SDK 生态提供了运行时创建、传递、认证与释放对象能力的安全基础设施。理解这套设计的核心约束(scope 唯一、seal 一次、claim 必调、多所有者语义),是正确使用 x/capability 与 IBC 能力认证流程的前提。