1 个稳定版本

9.0.1 2022年10月20日

#26 in #filecoin-actors


fil_builtin_actors_state 中使用

MIT/Apache

195KB
4K SLoC

内置 Filecoin 演员们

此存储库包含从 2022 年 7 月 6 日网络版本 16、时代 1960320 开始运行的 Filecoin 网络的链上内置演员的代码。

这些演员是用 Rust 编写的,旨在在 Filecoin 虚拟机 内运行。后者的一个参考实现位于 filecoin-project/ref-fvm

此存储库的构建过程将每个演员编译成 Wasm 字节码,并生成一个聚合包以供所有客户端导入。此包的结构是标准化的。以下为详细信息。

此代码库在 FIP-0031 中得到了规范。因此,从网络版本 16 以后,该网络只认可此演员实现。

预 FVM 演员们

以下 nv16 之前的网络版本的演员也在此实现

  • nv14 演员以方便测试。
  • nv15 演员以启用 nv15=>nv16 升级。

可导入的包

此存储库的主要输出是一个 CARv1 归档,将所有演员的 Wasm 字节码打包到一个文件中,具有以下特性

  • CARv1 头部指向一个单个根 CID。
  • 根CID解析为定义了Manifest类型(如下定义)的DAG-CBOR编码块,包含一个用于包格式的版本号(当前始终为1)和一个ManifestPayload的CID。
  • 以下定义的ManifestPayload包含在DAG-CBOR编码的块中,并定义了一种将演员类型名称与其对应的CID关联的类型。
  • 所有演员的CID都包含在同一CARv1存档中,与RAW块中的编译Wasm字节码一起。

Manifest 模式

# Manifest is encoded as: [version, CID]
type Manifest struct {
  version Int
  payload &ManifestPayload
} representation tuple

# ManifestPayload is encoded as: [ ["actorkey", CID], ["actorkey", CID], ... ]
#
# It alternatively may be interpreted as:
#   type ManifestPayload {String : &ActorBytecode} representation listpairs
# Or simply as a list of tuples.
type ManifestPayload struct {
  system &ActorBytecode
  init &ActorBytecode
  cron &ActorBytecode
  account &ActorBytecode
  storagepower &ActorBytecode
  storageminer &ActorBytecode
  storagemarket &ActorBytecode
  paymentchannel &ActorBytecode
  multisig &ActorBytecode
  reward &ActorBytecode
  verifiedregistry &ActorBytecode
  datacap &ActorBytecode
  placeholder &ActorBytecode
  evm &ActorBytecode
  eam &ActorBytecode
  ethaccount &ActorBytecode
} representation listpairs

# RAW block
type ActorBytecode bytes

预编译的演员包以本仓库中的发布二进制文件的形式提供。位于crates.io上的fil_builtin_actors_bundle包将不会更新。

发布

通过更改顶级Cargo.toml文件中的workspace.package.version,同时发布所有演员、运行时和状态抽象。

  1. workspace.package.version更改顶级Cargo.toml文件中的版本。
  2. 在GitHub上创建一个发布

这将触发GitHub CI的自动打包构建,生成的打包文件将附加到GitHub发布中。

客户端实现说明

获取演员包

有两种选择

  1. 从源代码构建。
  2. 从GitHub下载预编译的发布包。

从源代码构建说明(选项1)

  1. 克隆仓库。
  2. 检出相关分支或标签(见下文版本节)。
  3. 从工作区根目录执行make bundle

打包将写入output/builtin-actors.car

两种选项都支持通过脚本或CI管道自动化。

集成演员包

这部分是特定于实现的。选项包括

  1. 将包的CARv1字节嵌入到分发的二进制文件中。
  2. 启动时下载CARv1文件(使用某种形式的校验和以增加安全性)。

使用ref-fvm加载和使用演员包

一旦实现验证了包的完整性,它应该执行以下操作

  1. 将CARv1导入到块存储中。
  2. 按网络版本在内存中保留根CID,进行索引。
  3. 将根CID传递给ref-fvm的Machine构造函数,告诉ref-fvm哪个CodeCID映射到哪个内置演员。

支持多个网络版本

由于每个网络版本可能由不同的演员代码支持,实现应该准备好加载多个演员包并将它们按网络版本索引。

当实例化ref-fvm Machine时,必须传递网络版本和相应的Manifest根CID。

版本控制

一个合理的问题是,包版本如何与协议概念ActorVersion相关联。我们采用了类似于specs-actors的政策

  • 包版本中的主版本号与ActorVersion相关联。
  • 我们通常不使用次要版本;这些总是设置为0
  • 我们努力将主要包版本设置为圆形,以表示给定网络升级的最终发布。然而,由于无法预测软件工程的某些方面,这不是一条硬性规则,并且可能会通过增加修补程序编号来发布更多版本。

开发版本将使用如-rc(发布候选)之类的限定符。

以下是一个将此政策应用于v10演员版本谱系的示例

  • 不稳定开发版本通过提交哈希引用。
  • 稳定开发版本标记为发布候选版本:10.0.0-rc1,10.0.0-rc2,等等。
  • 最终发布版本:10.0.0。
  • 修复后的最终发布版本:10.0.1。
  • 修复后的最终发布版本:10.0.2。
  • 网络升级在10.0.2版本中上线。

关于这个代码库

与specs-actors的关系

此仓库取代了specs-actors,并承担两个角色

  • 内置actor的可执行规范。
  • 内置actor的规范、可移植实现。

致谢

此代码库最初是从Forest客户端的actors v6实现分支出来的,并适应了FVM环境。

社区

由于此代码库是所有Filecoin客户端实现中的公共财富,它为所有Core Devs提供了一个汇聚点,无论他们认同的实现或项目。

许可

双许可:通过MITApache软件许可v2,采用许可堆栈

除了EVM预编译测试数据外,它根据LGPL v3许可,不包括在crate或构建工件中。

依赖项

~11MB
~191K SLoC