Align Filecoin-FFI Versioning with Builtin-Actors Versioning

[rjan90]

Done Criteria:

The versioning of Filecoin-FFI should be updated to align with the versioning scheme used by the builtin-actors, and the Development Guideline gets cleaned up and adjusted accordingly.

Why Important:

The current tag/versioning of Filecoin-FFI is inconsistent with other repositories (Go-State-Types/Builtin-Actors) and currently maps to the Lotus version. Aligning the versioning will help maintain consistency across the project, reduce confusion, and improve the overall release process. This alignment will also help in tracking dependencies and ensuring compatibility between different components of the Filecoin project, especially around network upgrades.

User/Customer:

Maintainers and developers who depend on Filecoin-FFI.

Notes:

• Aligning the versioning will require updating the release process and possibly the tooling used for versioning.
• This change should be communicated clearly to all stakeholders to ensure a smooth transition.

[BigLep]

@rjan90 : thanks for creating the issue. I'm capturing some notes based on my understanding from conversations last week.

Repo	Versioning up through nv24	Versioning post nv24
Lotus	1.28.0 Even releases signifiy mandatory release per https://github.com/filecoin-project/lotus/blob/master/LOTUS_RELEASE_FLOW.md	1.INCREMENT_ON_NETWORK_UPGRADE_OR_API_BREAKING_CHANGE.x per filecoin-project/lotus#12072 Example: for nv24, Lotus will presumably be 1.29.0 (assuming no breaking changes beforehand).
filecoin-ffi	Tracks Lotus mandatory versions (e.g., 1.28.0)	0.ACTORS_VERSION.x (just like go-state-types) Not doing ACTORS_VERSION.x.x because of Go's handling of major versions greater than 1. Not doing 1.ACTORS_VERSION.x because there have already been releases with that version. This does mean that newer filecoin-ffi (e.g., 0.15.0 for nv25) will be lexicographically less than previous versions (e.g., 1.28.0).
go-state-types	0.ACTORS_VERSION.x (e.g., 0.14.0)	Same - no change.
builtin-actors	ACTORS_VERSION.0.0 (e.g., 14.0.0)	Same - no change.

I have wondered though if this change in network versioning is actually a good time to maybe break up the filecoin-ffi module into multiple? (I heard a couple of asks for it recently, but I can't remember the details - will capture it in an issue recently). I think it boiled down to the fact that some consumers only care about proofs while others only care about ref-fvm. We could allow them to update independently . (I don't know how much of a benefit that is vs. the cost of mainitaining more repos handling C and CGO bindings.)

[BigLep]

Relevant #fil-curio-dev thread: https://filecoinproject.slack.com/archives/C06GD1SS56Y/p1719449072359519

[Stebalien]

For context, we have 4 versions:

1. FVM.
2. Lotus.
3. Actor.
4. Network.

We update the FFI when we cut a new network upgrade because each FVM release checks if it supports the requested network version. If we changed anything here, we'd version by network version, not actor version, IMO.

The current tag/versioning of Filecoin-FFI is inconsistent with other repositories (Go-State-Types/Builtin-Actors) and currently maps to the Lotus version

The FFI was built to be a part of lotus, that's why it aligns with the lotus version.

The go-state-types track the actors version because they provide actor-version-specific types.

Aligning the versioning will help maintain consistency across the project, reduce confusion, and improve the overall release process

Can you expand on this?

This alignment will also help in tracking dependencies and ensuring compatibility between different components of the Filecoin project, especially around network upgrades.

I'm not sure how tracking lotus releases versus tracking actor releases makes a difference here.

• If you don't have the latest patch release of the FFI, your node may not go over the upgrade anyways.
• The FFI already tracks lotus releases. Is this an ask from venus?

---

I think all this boils down to the fact that the FVM refuses to run if the network version is beyond the supported range. How about we just remove that check?

[BigLep]

I'm finalizing circling back here @Stebalien as part of nv23 cleanup before nv24. Apologies for the delay. Your comments make sense and I understand more than I did a couple of months ago. I'll quote respond below.

we have 4 versions

Good reminder, thanks.

each FVM release checks if it supports the requested network version
I think all this boils down to the fact that the FVM refuses to run if the network version is beyond the supported range. How about we just remove that check?

I'm not up on this. Can you point me to where I can learn more?

If we changed anything here, we'd version by network version, not actor version, IMO.

That makes sense to me for clarity.

Writing things out from a network version perspective, for each network version:

• There are zero or one actors major versions (i.e., we can have a new network upgrade without an actors bump)
• There are zero or one go-state-types minor versions (since go-state-types minor versions track actors major versions)
• There are at least one Lotus minor version. (There are likely more since https://github.com/filecoin-project/lotus/blob/master/LOTUS_RELEASE_FLOW.md#minor-releases )

I don't know how to explain ref-fvm versions. I know there are multiple major versions at play per https://github.com/filecoin-project/filecoin-ffi/blob/master/rust/Cargo.toml . For each network upgrade, I don't know how these are impacted.

I don't know how to explain rust-fil-proofs. I assume there are zero or one rust-fil-proofs major versions per network version. I assume there can be minor or patch releases that don't require a network upgrade (e.g., fixing a security issue quickly).

The FFI was built to be a part of lotus, that's why it aligns with the lotus version.
The FFI already tracks lotus releases. Is this an ask from venus?

Understood that was the original intent. The "issue" we're facing is that there are other consumers besides Lotus (e.g., Curio). I think ideally non-Lotus consumers don't want to care about Lotus version. Curio raised this. I'm not sure if Venus cares.

---

So what do we do? Based on my still-not-fully-complete understand, I'm good to align on network version. This would look like:

0.NETWORK_VERSION.x
Not doing NETWORK_VERSION.x.x because of Go's handling of major versions greater than 1.
Not doing 1.ACTORS_VERSION.x because there have already been releases with that version.
This does mean that newer filecoin-ffi (e.g., 0.25.0 for nv25) will be lexicographically less than previous versions (e.g., 1.28.0).

---

Dump of dependencies of filecoin-ffil based on stars

I was curious...

pip install github-dependents-inf
github-dependents-info --repo filecoin-project/filecoin-ffi --markdownfile ~/Downloads/filecoin-ffi-usage.md --sort stars --verbose
cat ~/Downloads/filecoin-ffi-usage.md | grep -v "| 0 |" | grep -v "| 1 |"

Dependents stats for filecoin-project/filecoin-ffi

Package filecoin-project/filecoin-ffi

Repository	Stars
filecoin-project/lotus	2819
filecoin-project/venus	2053
textileio/powergate	384
application-research/estuary	239
textileio/textile	226
WorldDbs/lotus_test	173
filecoin-project/boost	110
filecoin-project/lassie	106
dapplink-labs/wallet-chain-node	95
filecoin-project/go-fil-markets	78
froghub-io/filecoin-sealer-recover	67
filecoin-project/lily	49
filedrive-team/go-graphsplit	43
application-research/filclient	41
filecoin-project/dealbot	32
textileio/bidbot	30
ipfs-force-community/go-fvm-sdk	30
filestar-project/lotus	30
FILCAT/ribs	25
filecoin-project/go-state-types	24
filecoin-project/sector-storage	24
pando-project/pando	23
application-research/autoretrieve	22
ipfs-force-community/damocles	21
ipfs-force-community/sophon-miner	21
ipfs-force-community/droplet	20
filswan/go-swan-client	20
filecoin-project/eudico	19
filecoin-project/venus-wallet	19
web3eye-io/Web3Eye	18
buidl-labs/Demux	18
filecoin-project/venus-sealer	17
filecoin-project/curio	16
application-research/delta	16
ipfs-and-filecoin/Coding-with-Filecoin-Homework	16
OB1Company/filehive	15
ipfs-force-community/sophon-messager	13
OpenFilWallet/OpenFilWallet	12
twosson/fildr-cli	12
aschmahmann/filexp	11
application-research/delta-edge	11
wcgcyx/fcr	11
filecoin-project/chain-validation	11
jsign/go-filsigner	10
filecoin-project/go-sectorbuilder	8
data-preservation-programs/spade	8
bsn-si/IPEHR-gateway	8
Zondax/rosetta-filecoin-proxy	8
ipfs-shipyard/w3rc	8
beck-8/sectors_penalty	7
filecoin-project/go-data-segment	7
llifezou/fil-wallet	7
filswan/swan-client	7
filecoin-box/lotus-box	6
ipfs-force-community/sophon-gateway	6
filecoin-shipyard/js-lotus-client-schema	6
labs3/filecoin-wallet-signing	5
application-research/barge	5
filmineio/telegraf-input-lotus	5
jimpick/lotus-retrieve-api-daemon	5
ipfs-force-community/venus-tool	4
textileio/broker-core	4
textileio/go-auctions-client	4
application-research/filclient-unstable	4
raulk/filnetdiag	4
filecoin-project/go-commp-utils	4
ZenGround0/ent	4
ribasushi/ltsh	4
filecash/lotus_builder	4
INFURA/lotus	3
Spacescope/meta-task	3
ribasushi/fil-naive-marketwatch	3
W3FS-ecore/w3fs	3
FILCAT/dagparts	3
nicobao/sutol	3
filecoin-project/lily-archiver	3
phantom-rabbit/filecoin	3
bugxzhu/lotus-1.4.0	2
froghub-io/lotus-load-balance-client	2
gmelodie/estuphotos	2
ribasushi/go-toolbox-interplanetary	2
protofire/wallaby	2
minerdao/lotus-sectors-counter	2
EpiK-Protocol/go-epik-gateway	2
NpoolPlatform/sphinx-proxy	2
renproject/nodectl	2
filepp/ipfc	2
Digital-MOB-Filecoin/filstats-cli	2
trustlessCapital/tc-dicm	2
Zondax/rosetta-filecoin-lib	2
FileXgov/Perry	2

Generated by github-dependents-info

[Stebalien]

each FVM release checks if it supports the requested network version
I think all this boils down to the fact that the FVM refuses to run if the network version is beyond the supported range. How about we just remove that check?

I'm not up on this. Can you point me to where I can learn more?

https://github.com/filecoin-project/ref-fvm/blob/464869e23830b6b546c0bb53b19b5d2b1d1620ae/fvm/src/machine/default.rs#L54-L60

We explicitly specify which versions the FVM supports just in case we introduce a feature in a network upgrade that requires a newer FVM version.

There are zero or one actors major versions (i.e., we can have a new network upgrade without an actors bump)

Yes.

There are zero or one go-state-types minor versions (since go-state-types minor versions track actors major versions)

Yes.

There are at least one Lotus minor version. (There are likely more since https://github.com/filecoin-project/lotus/blob/master/LOTUS_RELEASE_FLOW.md#minor-releases )

Not quite. We can have multiple network versions per lotus version. E.g., when we have two-stage upgrades where one network version enables some new feature and the next version disables the deprecated feature.

I don't know how to explain ref-fvm versions. I know there are multiple major versions at play per https://github.com/filecoin-project/filecoin-ffi/blob/master/rust/Cargo.toml . For each network upgrade, I don't know how these are impacted.

In the ref-fvm, we:

1. Use the major version whenever we need to make large structural changes where maintaining backwards compatibility without accidentally introducing state mis-matches would be difficult. Basically, major versions drop support for prior network versions. This lets us import multiple copies of the FVM (one per major version) so we can continue to execute/explore old network state.
2. Use the minor version to indicate potentially breaking rust API changes. Minor versions keep support for prior network versions. This is how most rust projects would use their major version.
3. Use the patch version to indicate that the release is API (rust) compatible with the previous release. Patch releases may add support for new network versions, fix bugs, etc.

We'd like to switch the FVM to strict semver.

I don't know how to explain rust-fil-proofs. I assume there are zero or one rust-fil-proofs major versions per network version. I assume there can be minor or patch releases that don't require a network upgrade (e.g., fixing a security issue quickly).

Yes. rust-fil-proofs follows rust semver so major versions indicate API-breaking changes, minor versions indicate new features, and patch versions indicate bug fixes.

Understood that was the original intent. The "issue" we're facing is that there are other consumers besides Lotus (e.g., Curio). I think ideally non-Lotus consumers don't want to care about Lotus version. Curio raised this. I'm not sure if Venus cares.

Their proposed solution doesn't address their problem because patch releases and bug fixes are a thing. The only solution is to coordinate.

[Stebalien]

So what do we do? Based on my still-not-fully-complete understand, I'm good to align on network version.

I would like to see curio actually argue for why this matters to them instead of us trying to guess why they might want it. The fact that there's nobody from curio in this thread makes me think we should just close this issue and move on.

Not doing 1.ACTORS_VERSION.x because there have already been releases with that version.

If we did anything, I'd bump to v2 and use 2.NETWORK_VERSION.x (clear semver violation, but not much we can do). However, that has a significant downside (the same issue we currently have in the FVM): both bug fixes and features will be forced to use patch releases. But I guess that's not the end of the world.

I wouldn't use 0.y.x because, IMO, that's confusing given the prior releases.

[BigLep]

Thanks for the info @Stebalien. I am good to close this and maintain the status quo given Curio hasn't engaged and made a stronger case. Before doing so, I'd like to:

1. Create a PR to ref-fvm that covers:
   • Current ref-fvm versioning scheme (using info in this issue) and links to discussions to change it (e.g., ref-fvm version philosophy  ref-fvm#358, FVM versioning and technical debt ref-fvm#1724)
   • Table summarizing what fvm major versions map to what network versions:
     • v2: 15-17 per https://github.com/filecoin-project/ref-fvm/blob/release/v2/fvm/src/machine/default.rs#L64
     • v3: 18-20 per https://github.com/filecoin-project/ref-fvm/blob/release/v3/fvm/src/machine/default.rs#L63
     • v4: 21+ per https://github.com/filecoin-project/ref-fvm/blob/master/fvm/src/machine/default.rs#L55
2. Create a PR to https://github.com/filecoin-project/lotus/blob/master/documentation/misc/Building_a_network_skeleton.md that gives a "Lotus and its major dependencies version overview in light of network versions" that captures the conversation above how lotus node, filecoin-ffi, builtin-actors, go-state-types, and ref-fvm versions relate to network versions.

@rjan90 : I feel like I had seen some of the above in docs before but I can't find it now. Let me know if it exists. If not, I'lll draft.

[BigLep]

I'm closing this now since have open the ref-fvm and Lotus docs PRs:
filecoin-project/ref-fvm#2050
filecoin-project/lotus#12481