内置 Filecoin Actor

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

这些Actor用Rust编写，旨在在Filecoin虚拟机内运行。后者在filecoin-project/ref-fvm中存在一个参考实现。

此仓库的构建过程将每个Actor编译成Wasm字节码，并生成一个汇总包以供所有客户端导入。此包的结构是标准化的。详细信息请见下文。

此代码库已在FIP-0031中标准化。因此，从网络版本16开始，此Actor实现是网络唯一认可的。

FVM之前Actor

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

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

可导入的包

此仓库的主要输出是一个CARv1存档，将所有Actor的Wasm字节码打包成一个文件，具有以下特性

• CARv1头指向一个单一的根CID。
• 根CID解析为定义了一个Manifest类型（如下定义）的DAG-CBOR编码块，该类型包含一个版本号用于描述包格式（目前总是1）以及一个指向ManifestPayload的CID。
• ManifestPayload（如下定义）包含在一个DAG-CBOR编码块中，并定义了一个类型，该类型将actor类型名与相应的CID关联。
• 所有actor的CID都包含在与RAW块中包含的编译Wasm字节码相同的CARv1归档中。

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包将不会更新。

发布

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

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

这会触发GitHub CI自动构建bundle，生成的bundle将被附加到GitHub发布中。

客户端实现说明

获取actor包

有两种选择

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

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

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

bundle将被写入到output/builtin-actors.car。

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

集成actor包

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

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

使用ref-fvm加载和使用actors bundle

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

1. 将CARv1导入到blockstore中。
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演员版本谱系为例，说明该政策的应用。

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

关于此代码库

与specs-actors的关系

此存储库取代了specs-actors，并扮演两个角色

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

鸣谢

此代码库最初是从Forest客户端的actors v6实现中分叉的，并适应了FVM环境。

社区

由于此代码库是所有Filecoin客户端实现中的公共财富，因此它成为所有核心开发者（无论他们认同哪种实现或项目）的汇聚点。

许可证

双许可：通过MIT、Apache软件许可证v2以及许可许可证栈进行许可。

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