diff --git a/docs/mesa-upgrade/appendix.mdx b/docs/mesa-upgrade/appendix.mdx new file mode 100644 index 000000000..9ec8e106e --- /dev/null +++ b/docs/mesa-upgrade/appendix.mdx @@ -0,0 +1,64 @@ +--- +title: Appendix +sidebar_label: Appendix +hide_title: true +description: Mesa Upgrade Appendix +keywords: + - Mesa + - upgrade + - appendix +--- + +# Appendix + +## Upgrading archive nodes from Berkeley to Mesa + +Below we present details of what changed in the archive node database schema between Berkeley and Mesa versions. + +### Extended zkApp State Fields + +Both zkApp state tables have been modified to support additional state elements: + +**zkapp_states_nullable table** + - Added columns `element8` through `element31` (nullable integer fields) + - Each new column references `zkapp_field(id)` + - These fields allow zkApps to store additional state information beyond the original 8 elements + +```sql +ALTER TABLE zkapp_states_nullable ADD COLUMN IF NOT EXISTS element8 INT REFERENCES zkapp_field(id); +... +ALTER TABLE zkapp_states_nullable ADD COLUMN IF NOT EXISTS element31 INT REFERENCES zkapp_field(id); +``` + +**zkapp_states table** + - Added columns `element8` through `element31` (non-nullable integer fields) + - Each new column references `zkapp_field(id)` with a default value pointing to the zero field + - Unlike the nullable version, these fields are required and default to the zero field ID + +```sql +ALTER TABLE zkapp_states ADD COLUMN IF NOT EXISTS element8 INT DEFAULT NOT NULL REFERENCES zkapp_field(id); +... +ALTER TABLE zkapp_states ADD COLUMN IF NOT EXISTS element31 INT DEFAULT NOT NULL REFERENCES zkapp_field(id); +``` + +This expansion allows zkApps to store up to 31 state elements instead of the previous 8, significantly increasing the state storage capacity for complex smart contracts. + +### Version Tracking + +The upgrade introduces a new `version` table to keep track of the database schema version. The purpose of this table is to help with future database migrations. The table tracks which migration scripts were applied and when. + +**version table** +```sql +CREATE TABLE IF NOT EXISTS version ( + version_num INT PRIMARY KEY, + applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +``` + +The version table provides: +- **Migration tracking**: Records which migrations have been applied +- **Timestamp tracking**: Shows when each migration was executed +- **Idempotency**: Prevents duplicate migration runs +- **Version identification**: Easily identify the current database schema version + +The table is created if it does not exist already. Rollback and upgrade scripts will insert a new row with the version number and timestamp when the script was applied. \ No newline at end of file diff --git a/docs/mesa-upgrade/flags-configs.mdx b/docs/mesa-upgrade/flags-configs.mdx new file mode 100644 index 000000000..e0bb0bcc2 --- /dev/null +++ b/docs/mesa-upgrade/flags-configs.mdx @@ -0,0 +1,137 @@ +--- +title: Post-Upgrade Flags and Configurations for Mainnet +sidebar_label: Post-Upgrade Flags and Configurations +hide_title: true +description: Post-Upgrade Flags and Configurations for Mainnet +keywords: + - Mesa + - upgrade + - flags + - configurations +--- + +# Post-Upgrade Flags and Configurations for Mainnet + +Please refer to the Mesa node release notes [here](https://github.com/MinaProtocol/mina/releases/tag/4.0.0). + +### Network details + +``` +Chain ID +a7351abc7ddf2ea92d1b38cc8e636c271c1dfd2c081c637f62ebc2af34eb7cc1 + +Git SHA-1 +ae112d3a96fe71b4ccccf3c54e7b7494db4898a4 + +Seed List +https://bootnodes.minaprotocol.com/networks/mainnet.txt + +Node build +https://github.com/MinaProtocol/mina/releases/tag/4.0.0 +``` + +### Block Producer's + +Start your node post-upgrade in Mainnet with the flags and environment variables listed below. + +``` +mina daemon +--block-producer-key +--config-directory +--file-log-rotations 500 +--generate-genesis-proof true +--libp2p-keypair +--log-json +--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt + +ENVIRONMENT VARIABLES +RAYON_NUM_THREADS=6 +MINA_LIBP2P_PASS +MINA_PRIVKEY_PASS +``` + +### SNARK Coordinator +Configure your node post-upgrade in Mainnet with specific flags and environment variables as listed. + +``` +mina daemon +--config-directory +--enable-peer-exchange true +--file-log-rotations 500 +--libp2p-keypair +--log-json +--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt +--run-snark-coordinator +--snark-worker-fee 0.001 +--work-selection [seq|rand|roffset] + +ENVIRONMENT VARIABLES +MINA_LIBP2P_PASS +``` + +### SNARK Workers +Connect to a SNARK Coordinator node if required and run the following flags. +``` +mina internal snark-worker +--proof-level full +--shutdown-on-disconnect false +--daemon-address + +ENVIRONMENT VARIABLES +RAYON_NUM_THREADS:8 +``` + +### Archive Node +Running an Archive Node involves setting up a non-block-producing node and a PostgreSQL database configured with specific flags and environment variables. + +For more information about running archive nodes, see [Archive Node](/node-operators/archive-node). + +The PostgreSQL database requires two schemas: +1. The PostgreSQL schema used by the Mina archive database: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/4.0.0) +2. The PostgreSQL schema extensions to support zkApp commands: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/4.0.0) + +The non-block-producing node must be configured with the following flags: +``` +mina daemon +--archive-address : +--config-directory +--enable-peer-exchange true +--file-log-rotations 500 +--generate-genesis-proof true +--libp2p-keypair +--log-json +--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt + +ENVIRONMENT VARIABLES +MINA_LIBP2P_PASS +``` + +This non-block-producing node connects to the archive node with the addresses and port specified in the `--archive-address` flag. + +The **archive node** command looks like this: + +``` +mina-archive run +--metrics-port +--postgres-uri postgres://:@
:/ +--server-port 3086 +--log-json +--log-level DEBUG +``` + +### Rosetta API +Once you have the Archive Node stack up and running, start the Rosetta API Docker image with the following command: + +``` +docker run +--name rosetta --rm \ +-p 3088:3088 \ +--entrypoint '' \ +minaprotocol/mina-rosetta:4.0.0-bullseye-mainnet \ +/usr/local/bin/mina-rosetta \ +--archive-uri "${PG_CONNECTION_STRING}" \ +--graphql-uri "${GRAPHQL_URL}" \ +--log-json \ +--log-level ${LOG_LEVEL} \ +--port 3088 +``` diff --git a/docs/mesa-upgrade/requirements.mdx b/docs/mesa-upgrade/requirements.mdx new file mode 100644 index 000000000..ba03a1486 --- /dev/null +++ b/docs/mesa-upgrade/requirements.mdx @@ -0,0 +1,67 @@ +--- +title: Requirements +sidebar_label: Requirements +hide_title: true +description: Mesa upgrade is a major upgrade that requires all nodes in a network to upgrade to a newer version. It is not backward compatible. +keywords: + - Mesa + - upgrade + - hardware requirements +--- + +# Requirements + +## Hardware Requirements + +Please note the following are the hardware requirements for each node type after the upgrade: + +| Node Type | Memory | CPU | Storage | Network | +|--|--|--|--|--| +| Mina Daemon Node | 32 GB RAM | 8 core processor with BMI2 and AVX CPU instruction set are required | 64 GB | 1 Mbps Internet Connection | +| SNARK Coordinator | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection | +| SNARK Worker | 32 GB RAM | 4 core/8 threads per worker with BMI2 and AVX CPU instruction set are required | 64 GB | 1 Mbps Internet Connection | +| Archive Node | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection | +| Rosetta API standalone Docker image | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection | +| Mina Seed Node | 64 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection | + +## Mina Daemon Requirements + +### Installation + +:::caution + +If you have `mina-generate-keypair` installed, you will need to first `sudo apt remove mina-generate-keypair` before installing `mina-mainnet=4.0.0`. +The `mina-generate-keypair` binary is now installed as part of the mina-mainnet package. + +::: + +### IP and Port configuration + +**IP:** + +By default, the Mina Daemon will attempt to retrieve its public IP address from the system. If you are running the node behind a NAT or firewall, you can set the `--external-ip` flag to specify the public IP address. + +**Port:** + +Nodes must expose a port publicly to communicate with other peers. +Mina uses by default the port `8302` which is the default libp2p port. + +You can use a different port by setting the `--external-port` flag. + +### Node Auto-restart + +Ensure your nodes are set to restart automatically after a crash. For guidance, refer to the [auto-restart instructions](/node-operators/block-producer-node/connecting-to-the-network#start-a-mina-node-with-auto-restart-flows-using-systemd) + +## Seed Peer Requirements + +### Generation of libp2p keypair + +To ensure connectivity across the network, it is essential that all seed nodes start with the **same** `libp2p` keypair. +This consistency allows other nodes in the network to reliably connect. +Although the same libp2p keys can be reused from before the upgrade, if you need to manually generate new libp2p keys, use the following command: + +``` +mina libp2p generate-keypair --privkey-path +``` + +Further information on [generating key pairs](/node-operators/generating-a-keypair) on Mina Protocol. diff --git a/docs/mesa-upgrade/upgrade-steps.mdx b/docs/mesa-upgrade/upgrade-steps.mdx new file mode 100644 index 000000000..26c38dc39 --- /dev/null +++ b/docs/mesa-upgrade/upgrade-steps.mdx @@ -0,0 +1,129 @@ +--- +title: Upgrade Steps +sidebar_label: Upgrade Steps +hide_title: true +description: Detailed upgrade steps and operators' tasks +keywords: + - Mesa + - upgrade + - Detailed upgrade steps and operators' tasks +--- + +# 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](https://docs.google.com/document/d/1rTmJvyaK33dWjJXMOSiUIGgf8z7turxolGHUpVHNxEU/edit#heading=h.2hqz0ixwjk3f) to confirm they have covered the required steps. + - Upgrade their nodes to the 3.2.0 stable version + - Ensure servers are provisioned to run Mesa nodes, meeting the new hardware requirements + - Upgrade their nodes to the node version [4.0.0](https://github.com/MinaProtocol/mina/releases/tag/4.0.0), with stop-slots, when this version becomes available + - Run upgrade script for the archive node if they run archive nodes and wish to upgrade 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 ([4.0.0](https://github.com/MinaProtocol/mina/releases/tag/4.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](https://docs.google.com/document/d/1rTmJvyaK33dWjJXMOSiUIGgf8z7turxolGHUpVHNxEU). +1. Provision servers that meet the minimum hardware requirements, including 32GB RAM and support for _AVX_ and _BMI2_ CPU instructions. +1. Upgrade nodes to node version [4.0.0](https://github.com/MinaProtocol/mina/releases/tag/4.0.0) ([4.0.0](https://github.com/MinaProtocol/mina/releases/tag/4.0.0) has built-in stop slots). + +### Archive Node Operators and Rosetta Operators +- Two upgrade 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 archive node upgrade. Since Mainnet is a long-lived network, the upgrade process is a very fast operation and boils down to running the upgrade script against your archive. It should not take more than 1 minute, depending on your server specification and infrastructure. + - For more information on the archive node upgrade process, please refer to the [Archive Upgrade](/mesa-upgrade/archive-upgrade) section. +2. Upgrade all nodes to the latest stable version [4.0.0](https://github.com/MinaProtocol/mina/releases/tag/4.0.0). +3. Provision servers that meet the minimum hardware requirements, primarily 32GB RAM. +4. 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 Mesa's new features. Pay special attention to: + - If you rely on the archive node SQL database tables, please review the schema changes in Appendix 1 of this document. +2. Upgrade all nodes to the latest stable version [4.0.0](https://github.com/MinaProtocol/mina/releases/tag/4.0.0). +3. Provision servers that meet the minimum hardware requirements, particularly 32GB RAM. +4. 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. +2. Execute the archive node upgrade script, which is backward compatible. +3. Continue to run archive node until after the network stops at the stop-network slot. +4. For more information on the archive node upgrade process, please refer to the [Archive Upgrade](/mesa-upgrade/archive-upgrade) 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 Mesa build, which will be used to initiate the upgraded network. It is during the upgrade windows that the Mesa 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 Mesa node was built from the pre-upgrade network state. To validate, follow the instructions provided in this [location](https://github.com/MinaProtocol/mina/blob/mesa/docs/upgrading-to-mesa.md) + +### Block Producers and SNARK Workers +1. During the upgrade phase (between _stop-network-slot_ and the publishing of the Mesa release), block producers can shut down their nodes. +2. After the publication of the Mesa 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 Mesa 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 Mesa 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 Mesa 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 Mesa archive process to the newly created database. + +### Exchanges +1. Exchanges shall disable MINA deposits and withdrawals during the entirety of the upgrade downtime, since the _stop-transaction-slot_ until the Mainnet Mesa network is operational. +2. After the Mesa 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 Mesa node release, at a predefined slot (Mesa 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 Mesa release. If you wish to provide Node Status and Error metrics and reports to o1Labs, 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 Mesa 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. diff --git a/sidebars.js b/sidebars.js index 0cfff6d68..d9598af18 100644 --- a/sidebars.js +++ b/sidebars.js @@ -40,7 +40,17 @@ module.exports = { { type: 'category', label: 'Mesa Upgrade', - items: ['mesa-upgrade/preflight-network', 'mesa-upgrade/archive-upgrade'], + link: { + type: 'doc', + id: 'mesa-upgrade/requirements', + }, + items: [ + 'mesa-upgrade/preflight-network', + 'mesa-upgrade/upgrade-steps', + 'mesa-upgrade/archive-upgrade', + 'mesa-upgrade/flags-configs', + 'mesa-upgrade/appendix', + ], }, { type: 'category',