Network version (nv) namespacing

[raulk]

Context

We are soon launching Hyperspace (see #544). This is a non-resetting developer preview network. It will start on a beta version for nv18 (FEVM upgrade) and will upgrade over the next week towards more mature releases, eventually culminating with the final nv18. From then onwards, it will move on to subsequent preview iterations of future FVM releases.

Because this network conducts upgrades, every new release that gets deployed needs a new network version (nv). The network version is an incrementing ordinal that tracks the protocol version the network is running.

Because Hyperspace upgrades through several pre-production releases on every cycle, it is the first network that will have a diverging version lineage from mainnet by design, e.g. nv18 on Hyperspace is a version different to nv18 on mainnet.

If we don't do anything, we might end up with:

Hyperspace	Mainnet
	nv17
nv18
nv19
nv20
	nv18
nv21
nv22
nv23
	nv19

This outcome is confusing and ambiguous for all stakeholders (e.g. nv18 means something different in A or B) and we'd like to propose a way to solve for this so that network versions can be referred to univocally.

Options

1. Do nothing and accept the ambiguity and expected confusion.
2. Introduce a first-class network qualifier field at some level in client implementations, such that it acts as the standard way of designating and identifying a network (and therefore categorizes the version lineage). However, this is quite difficult and breaking.
3. Realise that the network version is a u64 and 2^64 is a huge number of lineal network versions to ship, ever. Partition the uint64 type into two ranges through a bitmask, and overload it so that it carries more information used to disambiguate/sequence/namespace, e.g. (a) major.minor versions, (b) network::version.

Proposal

We propose to adopt option 3b, inspired by IP subnet masks, but simpler. We define a 16-bit bitmask (65536) over the highest bits (0xffff000000000000) of the full u64 network version to designate the namespace. The lowest 48 bits designate the version within that namespace. We thus overload the network version with new metadata.

The following networks versioning lines live under namespace 0x0000, which is fully backwards compatible with existing network versions in the history of these networks:

• Mainnet
• Calibrationnet
• Wallaby (resetting network, always running a future projected network version)
• Butterfly (also resetting)

The following network versioning lines live under namespace 0x0001:

• Hyperspace

Version 1 under Hyperspace would thus be: 0x0001000000000001 (decimal: 281474976710657). We could make this namespace identical to its ChainID though (decimal 3141).

Tradeoffs

• (+) This solution introduces no new physical protocol concepts. It's entirely convention-based.
• (+) It's fully backwards compatible.
• (+) It's not overeager with the range reservations, and in practice there is still room to add more metadata in the next 2 bytes of the network version following the namespace.
• (-) Decimal representations of network numbers with the non-zero namespace are non-intuitive and long.

Next steps

1. Trigger community discussion around the adoption of this convention.
2. If positive, eventually encode in an FRC.
3. Create a network namespace registry, probably within the same FRC.

Acknowledgements

@magik6k for proposing the preferred solution in a huddle (winner!).
@Stebalien @vyzo @jennijuju @arajasek @ZenGround0 for participating in preceding discussion.

[jennijuju]

Thanks for the write up! In general i like the idea.

We could make this namespace identical to its ChainID though (decimal 3141).

im in favour of this, set a good pattern in case we add new network in the future.

[anorth]

There is already a first-class network name (string) present in the init actor's state. So a large amount of (2) is already done. A network version without attached name will still need clarification, though.

One historical use of network versions is to trigger changes in behaviour within the built-in actors when the network reaches a certain point. This permits deployment of new actor code ahead of a change actually taking effect, with no need for a migration at that point in time. With true compiled actors we'd still need a migration just to install the actor code at some point before a network-version-triggered change, but we would have the ability to stage multiple behaviour changes in a single code upgrade in this way.

This pattern was necessary when we didn't have actor code content-addressed. Now that we do, there's an alternative option of triggering change by replacing the actor code when the network version ticks over – i.e. triggering the changed behaviour externally to the built-in actors rather than from within.

If network version numbers don't mean the same thing in different networks, it will be impractical to ever code a version-triggered change inside the actors. (We certainly wouldn't want to also encode knowledge of the different network names and version histories inside the actor code).