Skip to main content

Upgrade Steps

Mainnet Upgrade steps

Below it's the description in detail of all the upgrade steps and what which node operator type should do to in each step.

Pre-Upgrade​

  • During the Pre-Upgrade phase, node operators should prepare for the upcoming upgrade. The most important steps are:
    • Review the upgrade readiness checklist to confirm they have covered the required steps.
    • Upgrade their nodes to the 1.4.1 stable version
    • Ensure servers are provisioned to run Berkeley nodes, meeting the new hardware requirements
    • Upgrade their nodes to the node version 3.0.0, with stop-slots, when this version becomes available
    • Start the archive node initial migration if they run archive nodes and wish to perform the migration in a decentralized manner

Please note: a simplified Node Status service will be part of the upgrade tooling and enabled by default in Pre-Upgrade release with the stop-slots (3.0.0). This feature will allow for a safe upgrade by monitoring the amount of upgraded active stake. Only non-sensitive data will be reported. If operators are not comfortable sharing their node version, they will have the option to disable the node version reports by using the appropriate node flag --node-stats-type none

Block Producers and SNARK Workers​

  1. Review the upgrade readiness checklist.
  2. Provision servers that meet the minimum hardware requirements, including the new 32GB RAM requirement and support for AVX and BMI2 CPU instructions.
  3. Upgrade nodes to node version 3.0.0 (3.0.0 has built-in stop slots).

Archive Node Operators and Rosetta Operators​

  • Two migration processes will be available to archive node operators: trustless and trustful. If the archive node operator wants to perform the trustless migration, they should follow these steps; otherwise, proceed to the Upgrade phase. The trustful migration will rely on o1Labs database exports and Docker images to migrate the archive node database and doesn’t require any actions at this stage.
  1. Trustless migration:
  • Perform the initial archive node migration. Since Mainnet is a long-lived network, the initial migration process can take up to 48 hours, depending on your server specification and infrastructure.
  • If your Mina Daemon, archive node, or PostgreSQL database runs on different machines, the migration performance will be greatly impacted.
  • For more information on the archive node migration process, please refer to the Archive Migration section.
  1. Upgrade all nodes to the latest stable version 3.0.0.
  2. Provision servers that meet the minimum hardware requirements, primarily the new 32GB RAM requirement.
  3. Upgrade their nodes to the version that includes built-in stop slots before the pre-defined stop-transaction-slot.

Exchanges​

  1. Make sure to test your system integration with Berkeley's new features. Pay special attention to:
  • If you use the o1labs/client-sdk library to sign transactions, you should switch to mina-signer https://www.npmjs.com/package/mina-signer. o1labs/client-sdk was deprecated some time ago and will be unusable once the network has been upgraded. Please review the migration instructions in Appendix
  • If you rely on the archive node SQL database tables, please review the schema changes in Appendix 1 of this document.
  1. Upgrade all nodes to the latest stable version 3.0.0.
  2. Provision servers that meet the minimum hardware requirements, particularly the new 32GB RAM requirement.
  3. Upgrade your nodes to the version that includes built-in stop slots before the pre-defined stop-transaction-slot.

State Finalization​

  • Between the predefined stop-transaction-slot and stop-network-slot, a stabilization period of 100 slots will occur. During this phase, the network consensus will not accept new blocks with transactions on them, including coinbase transactions. The state finalization period ensures all nodes reach a consensus on the latest network state before the upgrade.
  • During the state finalization slots, it is crucial to maintain a high block density. Therefore, block producers and SNARK workers shall continue running their nodes to support the network's stability and security.
  • Archive nodes should also continue to execute to ensure finalized blocks are in the database and can be migrated, preserving the integrity and accessibility of the network's history.

Block Producers and SNARK Workers​

  1. It is crucial for the network's successful upgrade that all block producers and SNARK workers maintain their block-producing nodes up and running throughout the state finalization phase.
  2. If you are running multiple daemons like is common with many operators, you can run one single node at this stage.
  3. If you are a Delegation Program operator, remember that your uptime data will continue to be tracked during the state finalization phase and will be considered for the delegation grant in the following epoch.

Archive Node Operators and Rosetta Operators​

If you plan to do the trustful migration, you can skip this step. If you are doing the trustless migration, then:

  1. Continue to execute the archive node to ensure finalized blocks are in the database and can be migrated.
  2. Continue to run incremental archive node migrations until after the network stops at the stop-network slot.
  3. For more information on the archive node migration process, please refer to the Archive Migration section

Exchanges​

Exchanges shall disable MINA deposits and withdrawals during the state finalization period (the period between stop-transaction-slot and stop-network-slot) since any transactions after the stop-transaction-slot will not be part of the upgraded chain.

Remember that although you might be able to submit transactions, the majority of the block producers will be running a node that discards any blocks with transactions.

Upgrade​

  • Starting at the stop-network-slot the network will not produce nor accept new blocks, resulting in halting the network. During the upgrade period, o1Labs will use automated tooling to export the network state based on the block at the slot just before the stop-transaction-slot. The exported state will then be baked into the new Berkeley build, which will be used to initiate the upgraded network. It is during the upgrade windows that the Berkeley network infrastructure will be bootstrapped, and seed nodes will become available. o1Labs will also finalize the archive node migration and publish the PostgreSQL database dumps for import by the archive node operators who wish to bootstrap their archives in a trustful manner.
  • There is a tool available to validate that the Berkeley node was built from the pre-upgrade network state. To validate, follow the instructions provided in this location

Block Producers and SNARK Workers​

  1. During the upgrade phase (between stop-network-slot and the publishing of the Berkeley release), block producers can shut down their nodes.
  2. After the publication of the Berkeley node release, block producers and SNARK workers should upgrade their nodes and be prepared for block production at the genesis timestamp, which is the slot when the first Berkeley block will be produced.
  3. It is possible to continue using the same libp2p key after the upgrade. Remember to adjust the new flag to pass the libp2p key to the node.

Archive Node Operators and Rosetta Operators​

  1. Upon publishing the archive node Berkeley release, archive node operators and Rosetta operators should upgrade their systems. There will be both Docker images and archive node releases available to choose from.
  2. Depending on the chosen migration method:
  • Trustless
    • Operators should direct their Berkeley archive process to the previously migrated database.
  • Trustful
    • Operators shall import the SQL dump file provided by o1Labs to a freshly created database.
    • Operators should direct their Berkeley archive process to the newly created database.

Please note: both the trustless and trustful migration processes will discard all Mainnet blocks that are not canonical. If you wish to preserve the entire block history, i.e. including non-canonical blocks, you should maintain the Mainnet archive node database for posterior querying needs.

Exchanges​

  1. Exchanges shall disable MINA deposits and withdrawals during the entirety of the upgrade downtime, since the stop-transaction-slot until the Mainnet Berkeley network is operational.
  2. After the Berkeley releases are published, exchanges should upgrade their nodes and prepare for the new network to start block production.

Post-Upgrade​

  • At approximately 1 hour after the publishing of the Berkeley node release, at a predefined slot (Berkeley genesis timestamp), block production will start, and the network is successfully upgraded.
  • Node operators can monitor their nodes and provide feedback to the technical team in case of any issues. Builders can start deploying zkApps.
  • Please note: The Node Status service will not be enabled by default in the Berkeley release. If you wish to provide Node Status and Error metrics and reports to Mina Foundation, helping monitor the network in the initial phase, please use the following flags when running your nodes:
    • --node-stats-type [full|simple]
    • --node-status-url https://nodestats.minaprotocol.com/submit/stats
    • --node-error-url https://nodestats.minaprotocol.com/submit/stats
      • The error collection service tries to report any node crashes before the node process is terminated

Block Producers and SNARK Workers​

  1. Ensure that all systems have been upgraded and prepared for the start of block production.
  2. Monitor nodes and network health, and provide feedback to the engineering team in case of any issues.

Archive Node Operators and Rosetta Operators​

  1. Ensure that all systems have been upgraded and prepared for the start of block production.
  2. Monitor nodes and network health, and provide feedback to the engineering team in case of any issues.

Exchange and Builders​

  1. After the predefined Berkeley genesis timestamp, block production will commence, and MINA deposits and withdrawals can be resumed.
  2. Ensure that all systems have been upgraded and prepared for the start of block production.
  3. Monitor nodes and network health, and provide feedback to the engineering team in case of any issues.