内置 Filecoin 角色程序

此仓库包含从 2022 年 7 月 6 日的网络版本 16，epoch 1960320 开始运行的 Filecoin 网络的链上内置角色程序的代码。

这些角色程序是用 Rust 编写的，并设计在 Filecoin 虚拟机 内部运行。后者的参考实现位于 filecoin-project/ref-fvm。

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

此代码库在 FIP-0031 中进行了规范。因此，从网络版本 16 开始，此角色实现是网络唯一认可的实现。

Pre-FVM 角色程序

此处还实现了以下网络版本在 nv16 之前的角色程序

• nv14 角色程序以方便测试。
• nv15 角色程序以启用 nv15=>nv16 升级。

可导入的包

此仓库的主要输出是一个 CARv1 归档，将所有角色的 Wasm 字节码打包到单个文件中，具有以下特性

• CARv1 报头指向一个单一的根 CID。
• 根CID解析为定义Manifest类型的DAG-CBOR编码块（定义见下文），该类型包含打包格式的版本号（目前始终为1）和ManifestPayload的CID。
• ManifestPayload（定义见下文）包含在DAG-CBOR编码块中，定义了一个类型，将actor类型名称与其对应的CID关联起来。
• 所有actor的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

预编译actor打包文件作为此仓库中的发布二进制文件提供。在crates.io上的fil_builtin_actors_bundle crate将不会更新。

发布

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

1. 在顶层Cargo.toml文件中更改workspace.package.version。
2. 在GitHub中创建一个发布。

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

客户端实现说明

获取actors打包文件

有两种选择

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

从源代码构建说明（选项1）

1. 克隆仓库。
2. 检出相关的分支或标签（见下文版本控制部分）。
3. 从工作区根目录执行make bundle。

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

这两种选项都适用于通过脚本或CI管道自动化。

集成actors打包文件

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

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

使用ref-fvm加载和actor打包文件

一旦实现验证了打包文件的真实性，它应该执行以下操作

1. 将CARv1导入到块存储中。
2. 按网络版本索引保留根CID在内存中。
3. 将根CID馈送到ref-fvm的Machine构造函数，告诉ref-fvm哪个CodeCID映射到哪个内置actor。

多网络版本支持

由于每个网络版本可能由不同的actor代码支持，实现应该准备好加载多个actor打包文件，并按网络版本对其进行索引。

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

版本控制

一个公平的问题是crate版本控制如何与协议概念ActorVersion相关联。我们采用与specs-actors类似的政策

• crate版本中的主版本号与ActorVersion相关联。
• 我们通常不使用次版本号；这些始终设置为0。
• 我们努力使主crate版本圆润，以表示给定网络升级的确切发布。然而，由于无法预测软件工程的某些方面，这不是一条硬性规则，并且可能会通过增加补丁号进行进一步的发布。

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

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

• 不稳定的发展版本通过提交哈希引用。
• 稳定的发展版本标记为发布候选：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的汇聚点，无论他们认同的实现或项目。

许可证

双许可：MIT，Apache软件许可证v2，通过许可堆栈。

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