内置Filecoin演员

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

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

此仓库的构建过程将每个演员编译成Wasm字节码，并生成一个聚合包供所有客户端导入。此包的结构是标准化的。下面将详细介绍。

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

FVM之前的演员

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

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

可导入包

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

• CARv1头部指向一个单一的根CID。
• 根CID解析为一个DAG-CBOR编码的块，该块定义了一个Manifest类型（以下定义），其中包含捆绑格式的版本号（目前始终为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. 在顶层的Cargo.toml文件中更改workspace.package.version。
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，并扮演两个角色

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

致谢

此代码库最初是从Forest客户端的actors v6实现中分叉而来，并被适配到FVM环境中。

社区

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

许可

双许可：通过MIT和Apache软件许可协议v2，通过许可许可堆栈。

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