Cosmos SDK 动态能力存储(Dynamic Capability Store)设计解析:ADR-003 与对象能力模型

原创2026-10-11 12:13:141,849 阅读
文章标签:区块链

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 之后。它负责:

  1. 按各模块此前认领过的密钥,用新创建的能力密钥填充内存 store;
  2. 阻止任何新的 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 文档阐述了这一模型的两条核心规则:

  1. 对象 A 只有持有对象 B 的引用时,才能向 B 发送消息;
  2. 对象 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 能力认证流程的前提。

登录后查看全文
cosmos-sdk