Delegation of Authority for F3 Parameter Setting

[Kubuxu]

Motivation

The Fast Finality (F3) feature for Filecoin requires comprehensive testing under mainnet conditions to ensure its effectiveness and reliability. These live network conditions are challenging to replicate in test environments, and thus, the parameters for F3 are contingent upon the results of these mainnet tests. By default this necessitates two distinct network upgrades: one enabling Storage Providers to update their software for testing purposes, and a subsequent one for setting the finalized parameters. (See filecoin-project/go-f3#800 for more info.)

Design

To streamline this process and enhance flexibility, we propose delegating the authority for setting F3 parameters to an on-chain contract so F3 activation in mainnet can be accomplished with one network upgrade rather than two. This contract will be responsible for managing a predefined set of parameters and making go/no-go decisions regarding their implementation.

Key Features

1. On-Chain Contract for Parameter Management:
   • Move the parameter setting from the build phase to an on-chain contract, allowing for a singular dynamic update based on real-time test results.
   • This contract will live in a new public repo (e.g., filecoin-project/f3-activation-contract).
     • Note: while we’ll restrict write access to the repo to Lotus, Forest, and Venus maintainers for general repo hygiene, repo write access isn’t the chief concern. The key decision is the groups that have the ability to update the state of the published mainnet contract (discussed more below).
2. Controlled Update Mechanism:
   • Parameter updates will require full consensus amongst each of the Filecoin implementations: Lotus, Forest, and Venus.
   • Each of the three implementation teams will send signed messages to authorize changes, ensuring security and agreement among stakeholders.
3. Components of the Signed Message:
   • Bootstrap Epoch: Specifies the activation time, set no sooner than 72 hours from message transmission. (This is intended to give the community an additional window to react in case there late-discovered issues with the parameters/rollout. See Proposed sequence / example timeline for more context.)
   • EC.DelayMultiplier: Adjusts the delay multiplier for the consensus mechanism.
   • EC.BaseDecisionBackoffTable: Defines the backoff strategy for consensus decisions.
   • EC.HeadLookback: Determines the how far behind EC is F3 running.
   • GPBFTConfig: Configures the parameters for the GPBFT consensus protocol.
   • CxConfig: Configuration of Chain Exchange protocol
   • PubSubConfig: Configuration of F3’s usage of PubSub.
   • CatchUpAlignment: Aligns catch-up processes with network requirements.
4. Finalization and Self-Disabling:
   • This would have “used once finalization”. The contract does not permit further updates if the currently set bootstrap epoch is in the past.
   • It is designed to automatically disable itself after a period of six months from contract creation, ensuring that any changes are deliberate and well-considered, while preventing indefinite alterations.
     • This means the bootstrap epoch must be within 6 months months of the contract creation.
     • If for some reason F3 still isn’t activated within this 6 month window, a network upgrade will be required to update client software to point to a new or updated contract.

Terminology

Below are common terms used through the rest of this document.

• nv25 - The network upgrade that will deliver the next batch of F3 protocol and code changes, which we also expect is the last network upgrade for activating F3 on mainnet.
• “the smart contract” - This is the smart contract referred to in this proposal that contains the “good parameter set” and the bootstrap epoch. The source code will live in a TBD repo (e.g., filecoin-project/f3-activation-contract) and its address and hash will be hardcoded in Lotus/Forest/Venus nv25-compatible releases.
• “good parameter set” - This is the set of F3 configuration parameters that will be determined as part of nv25 mainnet passive testing. This parameter set will have sustained demonstrated success in mainnet.
• “the multisig contract” - This is a standard off-the-shelf multisig EVM contract that will be the owner of “the smart contract”. As a result, “the smart contract” will only accept updates from this multisg contract. This is the mechanism by which we accomplish multi-stakeholder consensus of the Lotus, Forest, and Venus implementation teams.

Proposed sequence / example timeline

This is an expected sequence of events for using this proposed functionality with an example timeline to aid with clarity on decision points and review periods.

What?	When Starts?	When Completes?	Why?
create “the multisig contract”	whenever	before deploying “the smart contract” below	Serves as the owner of “the smart contract” and accomplishes multi-stakeholder consensus of the Lotus, Forest, and Venus implementation teams.
deploy “the smart contract” that implements this proposal	by 1 week before nv25 Lotus code freeze	by nv25 Lotus code freeze	Give community an opportunity to review/audit “the smart contract” before baking its address and hash into nv25 Lotus/Forest/Venus versions. It should follow the design in this proposal and comply with the constraints that have been outlined.
update Lotus/Forest/Venus to hardcode “the smart contract” address and hash	by nv25 Lotus code freeze	by nv25 Lotus code freeze	Prevent any tampering with “the smart contract”’s logic/constraints that were reviewed by the community.
nv25 activation		date X (ideally in Q1)	Filecoin mainnet nodes/miners now have code that has: 1. Improvements / learnings from the nv24 passive testing. 2. Additional knobs for nv25 passive testing. 3. Does a one-time setting of the F3 “good parameter set” based on querying “the smart contract” as discussed in this proposal.
nv25 passive testing	X + 1 or 2 days	X + 2 weeks	Empirical testing to ensure we have a “good parameter set” that works well on mainnet. There will be daily updates on progress and findings, like with nv24, here.
announce proposed f3 parameters, proposed activation date, and rationale for these	X+2.5 weeks (after nv25 passive testing)	X + 2.5 weeks	Give community full visibility into the proposed f3 “good parameter set” that would be one-time-set via “the smart contract” so we can get input and determine whether we need to make any adjustments. This would be both in English prose in a GitHub community discussion/issue and in PR for “the smart contract” code.
community review period	X+2.5 weeks (after public announcement / PR)	X + 3.5 weeks	Ensure there is buy-in (or at least not major active opposition) to the “good parameter set” and bootstrap epoch.
set the bootstrap epoch and “good parameter set” on “the smart contract” with an activation epoch (which is at least 3 days in the future)	X + 3.5 weeks (after community review period)	X + 3.5 weeks	Nodes that are participating in nv25 will pick up the “good parameter set” and start using them at the bootstrap epoch. Given the bootstrap epoch is sufficiently in the future, if an issue wasn’t caught in the previous review period, there is still time to abort by updating “the smart contract” with a bootstrap epoch further in the future and/or to deploy client software that ignores the “good parameter set” values in “the smart contract”.
(optional) publish new Lotus, Forest, and Venus versions with the f3 “good parameter set” inline and removal of delegated setting via smart contract	X + 3.5 weeks (after community review period)	X + 3.5 weeks	Operators aren’t required to update to this version, but it gives them a way to run code that no longer has an opening for delegated authority.
bootstrap epoch	X + 4 weeks (starts based on the bootstrap epoch that was set as part of publishing “the smart contract”.)	X + 4 weeks	This is what activates F3 on Mainnet. This is what the network has been building for months 🙂
active mainnet monitoring	X + 4 weeks (after bootstrap epoch)	Indefinite	F3 in Mainnet now become a default aspect that is monitored and reviewed given its importance for the network.

What checks and balances are in place?

1. “the smart contract” code will be open for review for at least a week to help catch any potential vulnerabilities.
   1. Note: we are not planning for this contract to be formally audited because of its simple logic and no user assets being directly at stake.
2. The nv25-compatible Lotus/Forest/Venus releases will hardcode “the smart contract” address and source code hash such that getting client’s to use a tampered-version would require a network version. The PRs for hardcoding “the smart contract” address and source code hash will be open for review for at least 2 days to allow for verification. (And of course since implementations are open source, the active address and source code hash can be verified at any point.)
3. Updating the state of “the smart contract” with the bootstrap epoch and “good parameter set” will require signing from “the mutlisig contract”, which has three separate but knowledgeable signing groups (Lotus, Forest, and Venus maintainers). The corresponding blockchain message id will be shared on Slack, GitHub, etc. for clear visibility.
4. The bootstrap epoch set in the message above will be at least 72 hours in the future, providing one more window to course correct.
5. “the smart contract” code will disregard any bootstrap updates that are 6 months in future of the contract creation date, ensuring this one-time setting mechanism has an upper bound. (It’s expected that its “used once finalization” will occur well before this “self-disablement”.)
6. The “good parameter set” and bootstrap epoch cannot be updated if “the smart contract” has a bootstrap epoch set that is in the past. (This is conform with “use only once and then finalize”.)

Next Steps

1. Get input on this proposal
2. Assuming signal of buyin, create an FRC
3. Start prototyping engineering items listed in Design a mechanism to reduce the need for two network upgrades for F3 activation to one go-f3#800

Authors @BigLep and @Kubuxu