Upgradability of the network

[xgreenx]

Overview

The network may have updates on different levels of the protocol. Some of them are optional, and each node is not required to support them. Others may require upgrading the binary for the whole network, causing a hard fork of the network.

There are several available strategies for upgradability:

• Forking the network by creating a new network with new rules for block production.
• Regenesis network in-place by replacing an old network with a new one with state migration.
• Launch a parallel independent network and provide the bridge between two networks.
• Support forkless upgrades, allowing changing logic on the fly for all nodes in the network.

Each solution has its pros and cons for each network participant (users, developers, operators, etc).

Our thoughts on upgradability

Fuel's goal is to provide an excellent experience for both DApp users and developers, as well as node operators and the core team. Because the protocol evolves and grows, we must be flexible enough to provide new functionality. At the same time, we don't want to support old, deprecated codebase versions for backward compatibility.

Because of those requirements, we've decided to choose a hybrid approach and use different upgrade strategies for different levels of modification to the protocol.

Categorization of modifications

• Major(Requires a new binary/state transition):
  • Blocks, transactions, Inputs, Outputs layout, new policies. It affects:
    • Networking
    • Database
    • API
    • State transition
  • State transition modification:
    • FuelVM opcodes behavior
    • Gas charging model(not only prices)
    • Bug fixes
  • Change in API behavior
  • Critical changes on the p2p level
• Minor(Doesn’t require a new binary/state transition):
  • Consensus parameters
  • New fields/endpoints in the API
  • New optional p2p protocol or version of protocols
  • Mempool update without affecting broadcasting
  • Bug fixes in the API
  • Performance optimisations
  • Peer reputation
  • Internal structure of the Database

All minor changes only affect the peer itself without hitting the network. The major changes initiate soft and hard forks and, in some cases, may cause a regenesis.

Solution for each category

Minor changes

Minor changes are mostly essential for RPC providers and DApp developers because they allow them to receive the latest features that may have quality-of-life improvements. But they don't affect the network except in performance cases. Improvements/Regressions in performance may affect the opcodes cost in the future, so transitively, it could affect consensus parameters. These changes do not require any network coordination and can be released as minor updates.

Major changes

Majors updates usually require the peers in the network to use a new binary that may be backward compatible with old blocks but not forward compatible.

Layout of public types

Modification in the public types layout affects all layers of the protocol, starting the blockchain and ending the user. Without forkless upgrade support across all layers(database, networking, API, state transition), there is only one way to support them: use a new binary causing hard fork. While versioning of the types solves most issues or at least provides a way of handling updates, the database suffers mostly and may require state migration.

This kind of modification is the most destructive. While it is possible to minimize the impact on the network by using forkless state transition updates and on-chain database migration, the API and p2p still suffer the most. Consumers like wallets, frontend, SDK, and Sway should still deal with the damage caused by these kinds of updates on their own. During the modification of the public types, we need to take into account migration/support strategy for consumers and try to make compatible changes.

State transition

The state transition is usually also a pain point for the blockchain because it always requires the usage of the latest binary, causing a hard fork. Plus, it adds complexity to the protocol itself in the case of backward compatibility support.

Supporting fraud proofs give us almost everything required to have forkless upgrade support for the state transition function and solves most of the upgradability problems, simplifying the development for the core team. It transforms the hard fork into a soft one, allowing bug fixes, adding new functionality, and changing consensus rules on the flight.

Also, in the case of simple modifications to the type layout, it is possible to perform on-chain state migration inside the state transition function.

Any kind of modification is backward and forward compatible, allowing even super-old binaries to continue network validation. But even with this nice feature, we still need to do updates carefully avoiding breaking deployed contracts. Adding new functionality is not a problem, but changing the behavior of the old one may cause bugs in logic or even break contract execution.

API behaviour

The current codebase uses GraphQL API style and supports queries and data not used by the protocol itself. At some point, we hope to move it to the indexer and replace GraphQL with gRPC. Because, in the end, the backend will contain only the required functionality for the protocol, it is hard to change the behavior of some existing API. Even if we do, it should be possible to support old and new behavior in almost all cases. So, versioning can be supported by introducing different endpoints.

It moves the API upgradability problem from the protocol to the indexers and SDKs.

Critical P2P changes

In the case of consensusless rollups, p2p is not critical for the network itself because there is a main ledger that finalizes the order of blocks/transactions. The current stage of Fuel is Proof of Authority, and the next one is either a shared sequencer or Proof of Stack. It will likely be a shared sequencer because it fits into our vision to have many Fuel rollups interconnected through the one finality layer - a shared sequencer.

While the set of block producers for one roll-up still requires some kind of consensus, the number of participants shouldn't be too high, and crucial P2P modifications can be coordinated off-chain and are optional since the SS is the main point of communication.

The P2P compatibility is more of a problem for the shared sequencer because it has many consumers - rollups.

The core team will still try to minimize the number of breaking P2P changes and will try to support old versions of the protocol.

Tracking of upgradability

• Versioning of public types #1544
• Versioning of the protocol-required database types #1552
• Database state migration #1545
• Feature: Forkless upgrade support #1546
• Proposal to move out GraphQL API from fuel-core to fuel-indexer #588

Regenesis

• Regenesis support #1693
• E2E testing of regenesis #1756
• Integration test for regenesis with massive data #1571

The dependencies graph

[xgreenx]

The major part of this feature is done. Only testing remains. I'm closing this issue since we have issue for tests #1756.

#588 is not part of the current scope of mainnet.