Repurposing BlockHeader.ForkSignaling for Network Coordination

[rvagg]

The BlockHeader.ForkSignaling field is a 64-bit integer that's been sitting (mostly) unused in the Filecoin chain block headers (type is described here).

During an in-person discussion at FDS-7 about the difficulty of determining network upgrade readiness there was a proposal to use ForkSignaling to actually do some signalling (from memory, @lanzafame, @BigLep and @rjan90 were present and contributed to this discussion). Currently the field is left as the default 0 value by Lotus Miner and Curio, and is set to 1 by Venus / sophon-miner.

This is an initial proposal of how we could use it to encode miner software identification, network upgrade readiness signals, and actors bundle verification into a structured bit layout that enables better network visibility and coordination.

Motivation

Right now, we have limited visibility into the Filecoin mining ecosystem. Which software are miners running? Are miners ready for upcoming network versions or do we need to chase them up? Are they really ready, with the latest actors bundle or do they have something else?

The ForkSignaling field gives us 64 bits to work with. Currently, only values 0 and 1 have been used (Venus/Sophon uses 1 for internal signaling). Let's define a proper schema.

Proposed Bit Layout

When mining a new block, a miner will encode the 64 bit field as follows:

Bits  0-1   (2 bits):  Format Version (=2 for this spec; 0-1 reserved for legacy)
Bits  2-5   (4 bits):  Miner Software ID (0=unknown, 1=Lotus, 2=Sophon, 3=Curio, etc.)
Bits  6-13  (8 bits):  Network Version (target upgrade version, 0=not signaling)
Bits 14-19  (6 bits):  Actors Major Version (0-63)
Bits 20-21  (2 bits):  Actors Minor Version (0-3)
Bits 22-25  (4 bits):  Actors Patch Version (0-15)
Bits 26-42  (17 bits): Upgrade Epoch Offset (epochs until upgrade, max ~45 days)
Bits 43-63  (21 bits): Actors Bundle CID Digest (last 21 bits of multihash)

• Version 2 lets us clearly differentiate from the current 0 and 1 in use in the wild.
• Bits 6-63 will be zero if the miner is not aware of a network upgrade scheduled within the next 30 days, but will be set to the known upgrade details if there is
• Actors semver numbering is slightly brittle and limited but assumes, based on history, that in practice:
  • minor version is unlikely to be used
  • patch version is likely to have some, but minor use
  • also, that by actors version 63 we'll be on some new improved scheme or an improvement to this format.
• Use of upgrade epoch offset from current to minimimise the number of bits required
• Use a slice of the bundle digest as a kind of checksum / sanity check on the actors bundle semver (there have been cases of mismatches)

The validity of this field would not be checked, so having it correctly formatted is not consensus-critical..

Miner Software IDs

A FIP (edit: this is probably an FRC, not a FIP) would also introduce a registry of miner software that can be updated by maintainers as new ones are introduced. We would start with:

0x0: Unknown/Unset
0x1: Lotus
0x2: Sophon (Venus)
0x3: Curio
0x4-0xF: Reserved for additional implementations

What This Enables

1. Upgrade readiness dashboards: Anyone can scan the chain and see what percentage of recent blocks signal readiness for nv29, nv30, etc.

2. Implementation diversity metrics: Track the health of the multi-client ecosystem over time.

3. Actors bundle verification: Quickly detect if miners are running mismatched or outdated bundles.

Backward Compatibility

• Legacy value 0: Treated as "no signal" (pre-spec blocks or miners not participating)
• Legacy value 1: Sophon's existing usage—decoders should recognize format version < 2 and ignore as legacy
• New signals: Format version = 2, fully structured per this spec

Existing chain history remains valid. Miners running older software simply won't populate the new fields, which is fine. This field has never been checked or validated and this will continue to be the case. Participation is opt-in.

[BigLep]

Thanks for starting this @rvagg . The proposal makes sense to me. A few things that I think could be added when converting this to an FRC.

Example

Lets assume the following (coming from https://github.com/filecoin-project/core-devs/blob/master/upgrades.json)

Network Version	Actors Version	Actors Bundle CID	Upgrade Epoch	Upgrade Epoch Friendly Name
v26	v16.0.0	FILL IN	5126520	nv26_upgrad_epoch
v27	v17.0.0	FILL IN	5348280	nv27_upgrad_epoch

Could we maybe outline what we'd expect BlockHeader.ForkSignaling to look like for these cases:

Epoch	Epoch comment	Actors version that supports	Actors version comment	Next network upgrade status
nv26_upgrade_epoch + 100	Some time after nv26 upgrade	v16.0.0	Actors version that matches what is expected for the current nework version	Upgrade epoch not known
nv27_upgrade_epoch - 5000	Getting closer to the nv27 upgrade	v16.0.0	Haven't upgraded to the newest bundle yet	Upgrade epoch known
nv27_upgrade_epoch - 100		v17.0.0	Have the actors bundle that is expected for the upcoming upgrade	Upgrade epoch known
nv27_upgrade_epoch + 1	After the network upgrade	v17.0.0	Have the actors bundle that is expected for the new network version	Upgrade epoch not known

I want to make sure it's clear how we show what version of actors is active right now vs. the version we're capable of supporting.

Upgrade path (i.e., make clear what happens if we need to make changes)

I assume if Bits 0-1 is 0b11 (i.e., 3), then that will correspond with a new potential format.

Motivations

I think you can also add how it's useful to determine which SPs have upgraded to the new network version as failure to upgrade can lead to F3 participation levels dropping below the minimum as we saw in filecoin-project/lotus#13359.

Other sources to potentially reference

FDS-7 notes: https://docs.google.com/document/d/1kxA2b5V0Hm0lSF8ZQxmqauBoh6wJWXINscDpEm3sTH4/edit?tab=t.y3uj8nmj7dfk#bookmark=id.21ljfg6h5xoz
(There is another issue somewhere, but I'm struggling to find it... I'll update when I do.)

[rvagg]

Noting also that @Kubuxu thinks we don't have enough bits for the version string in this proposal. We only get one more version bump, 3, then we're painted into a bit of a corner. So let's add another bit, that gives us version 2 to 7, and shave off one bit from the digest.

Regarding the digest - there are cases where we've had two different bundle hashes for the same version string so having part of the digest is quite helpful. I believe that 20 bits gives us 1 in 1,048,576 chance of random collision, 21 would be 2,097,152. BUT we also have control over this digest; if we ever accidentally had a bundle generation mishap where we needed to make a new one and be absolutely sure that we didn't conflict with a previous build, we could just jigger some bit in the build and have an entirely new bundle hash if we needed to, so the collisions wouldn't be entirely random, we could probably get away with many fewer bits if we were very intentional about our builds and watched for collisions with previous recent builds.

[Kubuxu]

I don't think I said that explicitly. In theory, when we bump to version 3, we can dedicate one more bit then. Having just the one bit IMO is good enough, but it is a trade-off, so I won't scuff at us having more space there.