From 23deac8327ade3899f556517ee67ad4dc40728d6 Mon Sep 17 00:00:00 2001 From: dkijania Date: Thu, 11 Dec 2025 12:00:29 +0100 Subject: [PATCH 1/3] added initial draft for upgrade to mesa --- docs/mesa-upgrade/appendix.mdx | 42 +++++++++ docs/mesa-upgrade/flags-configs.mdx | 137 ++++++++++++++++++++++++++++ docs/mesa-upgrade/requirements.mdx | 67 ++++++++++++++ docs/mesa-upgrade/upgrade-steps.mdx | 131 ++++++++++++++++++++++++++ sidebars.js | 12 ++- 5 files changed, 388 insertions(+), 1 deletion(-) create mode 100644 docs/mesa-upgrade/appendix.mdx create mode 100644 docs/mesa-upgrade/flags-configs.mdx create mode 100644 docs/mesa-upgrade/requirements.mdx create mode 100644 docs/mesa-upgrade/upgrade-steps.mdx diff --git a/docs/mesa-upgrade/appendix.mdx b/docs/mesa-upgrade/appendix.mdx new file mode 100644 index 000000000..fab79b17c --- /dev/null +++ b/docs/mesa-upgrade/appendix.mdx @@ -0,0 +1,42 @@ +--- +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 presents details what was changed in the archive node database schema between Berkeley and Mesa version. + +**Zkapp_state_nullable additional Columns ** + - The `zkapp_state_nullable` table has been modified to include a new columns `element8` to `element31` which are nullable and can store additional state information for zkApps. + +```sql +, element8 int REFERENCES zkapp_field(id) +... +, element31 int REFERENCES zkapp_field(id) +); + +``` + +**Version table** + +We also introduced a new table `version` to keep track of the database schema version. +Purpose of this table is to help with future database migrations. Table tracks which migration scripts were applied and when. +Ultimately it helps to determine the current version of the database schema. And helps to avoid applying the same migration script multiple times. + +This 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. + +```sql +CREATE TABLE IF NOT EXISTS version ( + version_num INT PRIMARY KEY, + applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +); +``` \ 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..2fd0d48c7 --- /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: + - Berkeley + - upgrade + - flags + - configurations +--- + +# Post-Upgrade Flags and Configurations for Mainnet + +Please refer to the Berkeley node release notes [here](https://github.com/MinaProtocol/mina/releases/tag/3.0.3). + +### 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/3.0.3 +``` + +### 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/3.0.3) +2. The PostgreSQL schema extensions to support zkApp commands: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.3) + +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:3.1.0-ae112d3-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..e17780c18 --- /dev/null +++ b/docs/mesa-upgrade/requirements.mdx @@ -0,0 +1,67 @@ +--- +title: Requirements +sidebar_label: Requirements +hide_title: true +description: Berkeley upgrade is a major upgrade that requires all nodes in a network to upgrade to a newer version. It is not backward compatible. +keywords: + - Berkeley + - 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=3.1.0-ae112d3`. +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..49476810b --- /dev/null +++ b/docs/mesa-upgrade/upgrade-steps.mdx @@ -0,0 +1,131 @@ +--- +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 [3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3), 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 ([3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3)). 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 the new 32GB RAM requirement and support for _AVX_ and _BMI2_ CPU instructions. +1. Upgrade nodes to node version [3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3) ([3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3) 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 [3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3). +3. Provision servers that meet the minimum hardware requirements, primarily the new 32GB RAM requirement. +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 [3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3). +3. Provision servers that meet the minimum hardware requirements, particularly the new 32GB RAM requirement. +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/berkeley/docs/upgrading-to-berkeley.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. + +**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 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 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 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', From e19daf83c0d7aeea60a1456eab99ea00b6fd2f50 Mon Sep 17 00:00:00 2001 From: dkijania Date: Thu, 11 Dec 2025 13:02:44 +0100 Subject: [PATCH 2/3] Review fixes: - remove information removal of non-canonical blocks - update description for schema changes --- docs/mesa-upgrade/appendix.mdx | 57 +++++++++++++++++++++-------- docs/mesa-upgrade/upgrade-steps.mdx | 2 - 2 files changed, 42 insertions(+), 17 deletions(-) diff --git a/docs/mesa-upgrade/appendix.mdx b/docs/mesa-upgrade/appendix.mdx index fab79b17c..0d34209ce 100644 --- a/docs/mesa-upgrade/appendix.mdx +++ b/docs/mesa-upgrade/appendix.mdx @@ -13,30 +13,57 @@ keywords: ## Upgrading archive nodes from Berkeley to Mesa -Below we presents details what was changed in the archive node database schema between Berkeley and Mesa version. +Below we present details of what changed in the archive node database schema between Berkeley and Mesa versions. -**Zkapp_state_nullable additional Columns ** - - The `zkapp_state_nullable` table has been modified to include a new columns `element8` to `element31` which are nullable and can store additional state information for zkApps. +### Extended zkApp State Fields + +**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 -, element8 int REFERENCES zkapp_field(id) +ALTER TABLE zkapp_states_nullable ADD COLUMN IF NOT EXISTS element8 INT REFERENCES zkapp_field(id); ... -, element31 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); ``` -**Version table** +### Migration History Tracking -We also introduced a new table `version` to keep track of the database schema version. -Purpose of this table is to help with future database migrations. Table tracks which migration scripts were applied and when. -Ultimately it helps to determine the current version of the database schema. And helps to avoid applying the same migration script multiple times. +The upgrade introduces a new `migration_history` table to track database schema migrations. This helps manage future upgrades and prevents applying the same migration multiple times. -This 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. +**migration_status enum type** +```sql +CREATE TYPE migration_status AS ENUM ('starting', 'applied', 'failed'); +``` +**migration_history table** ```sql -CREATE TABLE IF NOT EXISTS version ( - version_num INT PRIMARY KEY, - applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP +CREATE TABLE IF NOT EXISTS migration_history ( + commit_start_at TIMESTAMPTZ NOT NULL DEFAULT NOW() PRIMARY KEY, + protocol_version TEXT NOT NULL, + migration_version TEXT NOT NULL, + description TEXT NOT NULL, + status migration_status NOT NULL ); -``` \ No newline at end of file +``` + +The table tracks: +- **commit_start_at**: Timestamp when the migration started +- **protocol_version**: Target protocol version (e.g., '4.0.0' for Mesa) +- **migration_version**: Version of the migration script itself (e.g., '0.0.5') +- **description**: Human-readable description of the migration +- **status**: Current state of the migration (starting, applied, or failed) + +The migration script uses protocol version '3.0.0' for Berkeley and '4.0.0' for Mesa, with built-in safety checks to prevent reapplying migrations or running them on incorrect database versions. \ No newline at end of file diff --git a/docs/mesa-upgrade/upgrade-steps.mdx b/docs/mesa-upgrade/upgrade-steps.mdx index 49476810b..565f2886e 100644 --- a/docs/mesa-upgrade/upgrade-steps.mdx +++ b/docs/mesa-upgrade/upgrade-steps.mdx @@ -100,8 +100,6 @@ There will be both Docker images and archive node releases available to choose f - 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. -**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 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. From 087520fcdee5c0cfb3c11871b12d41e3c9109104 Mon Sep 17 00:00:00 2001 From: dkijania Date: Sat, 13 Dec 2025 20:22:56 +0100 Subject: [PATCH 3/3] appendix fix and renaming berkeley -> mesa --- docs/mesa-upgrade/appendix.mdx | 35 +++++++++++++---------------- docs/mesa-upgrade/flags-configs.mdx | 12 +++++----- docs/mesa-upgrade/requirements.mdx | 6 ++--- docs/mesa-upgrade/upgrade-steps.mdx | 20 ++++++++--------- 4 files changed, 34 insertions(+), 39 deletions(-) diff --git a/docs/mesa-upgrade/appendix.mdx b/docs/mesa-upgrade/appendix.mdx index 0d34209ce..9ec8e106e 100644 --- a/docs/mesa-upgrade/appendix.mdx +++ b/docs/mesa-upgrade/appendix.mdx @@ -17,6 +17,8 @@ Below we present details of what changed in the archive node database schema bet ### 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)` @@ -39,31 +41,24 @@ ALTER TABLE zkapp_states ADD COLUMN IF NOT EXISTS element8 INT DEFAULT NOT NULL REFERENCES zkapp_field(id); ``` -### Migration History Tracking +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. -The upgrade introduces a new `migration_history` table to track database schema migrations. This helps manage future upgrades and prevents applying the same migration multiple times. +### Version Tracking -**migration_status enum type** -```sql -CREATE TYPE migration_status AS ENUM ('starting', 'applied', 'failed'); -``` +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. -**migration_history table** +**version table** ```sql -CREATE TABLE IF NOT EXISTS migration_history ( - commit_start_at TIMESTAMPTZ NOT NULL DEFAULT NOW() PRIMARY KEY, - protocol_version TEXT NOT NULL, - migration_version TEXT NOT NULL, - description TEXT NOT NULL, - status migration_status NOT NULL +CREATE TABLE IF NOT EXISTS version ( + version_num INT PRIMARY KEY, + applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP ); ``` -The table tracks: -- **commit_start_at**: Timestamp when the migration started -- **protocol_version**: Target protocol version (e.g., '4.0.0' for Mesa) -- **migration_version**: Version of the migration script itself (e.g., '0.0.5') -- **description**: Human-readable description of the migration -- **status**: Current state of the migration (starting, applied, or failed) +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 migration script uses protocol version '3.0.0' for Berkeley and '4.0.0' for Mesa, with built-in safety checks to prevent reapplying migrations or running them on incorrect database versions. \ No newline at end of file +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 index 2fd0d48c7..e0bb0bcc2 100644 --- a/docs/mesa-upgrade/flags-configs.mdx +++ b/docs/mesa-upgrade/flags-configs.mdx @@ -4,7 +4,7 @@ sidebar_label: Post-Upgrade Flags and Configurations hide_title: true description: Post-Upgrade Flags and Configurations for Mainnet keywords: - - Berkeley + - Mesa - upgrade - flags - configurations @@ -12,7 +12,7 @@ keywords: # Post-Upgrade Flags and Configurations for Mainnet -Please refer to the Berkeley node release notes [here](https://github.com/MinaProtocol/mina/releases/tag/3.0.3). +Please refer to the Mesa node release notes [here](https://github.com/MinaProtocol/mina/releases/tag/4.0.0). ### Network details @@ -27,7 +27,7 @@ Seed List https://bootnodes.minaprotocol.com/networks/mainnet.txt Node build -https://github.com/MinaProtocol/mina/releases/tag/3.0.3 +https://github.com/MinaProtocol/mina/releases/tag/4.0.0 ``` ### Block Producer's @@ -87,8 +87,8 @@ Running an Archive Node involves setting up a non-block-producing node and a Pos 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/3.0.3) -2. The PostgreSQL schema extensions to support zkApp commands: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.3) +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: ``` @@ -127,7 +127,7 @@ docker run --name rosetta --rm \ -p 3088:3088 \ --entrypoint '' \ -minaprotocol/mina-rosetta:3.1.0-ae112d3-bullseye-mainnet \ +minaprotocol/mina-rosetta:4.0.0-bullseye-mainnet \ /usr/local/bin/mina-rosetta \ --archive-uri "${PG_CONNECTION_STRING}" \ --graphql-uri "${GRAPHQL_URL}" \ diff --git a/docs/mesa-upgrade/requirements.mdx b/docs/mesa-upgrade/requirements.mdx index e17780c18..ba03a1486 100644 --- a/docs/mesa-upgrade/requirements.mdx +++ b/docs/mesa-upgrade/requirements.mdx @@ -2,9 +2,9 @@ title: Requirements sidebar_label: Requirements hide_title: true -description: Berkeley upgrade is a major upgrade that requires all nodes in a network to upgrade to a newer version. It is not backward compatible. +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: - - Berkeley + - Mesa - upgrade - hardware requirements --- @@ -30,7 +30,7 @@ Please note the following are the hardware requirements for each node type after :::caution -If you have `mina-generate-keypair` installed, you will need to first `sudo apt remove mina-generate-keypair` before installing `mina-mainnet=3.1.0-ae112d3`. +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. ::: diff --git a/docs/mesa-upgrade/upgrade-steps.mdx b/docs/mesa-upgrade/upgrade-steps.mdx index 565f2886e..26c38dc39 100644 --- a/docs/mesa-upgrade/upgrade-steps.mdx +++ b/docs/mesa-upgrade/upgrade-steps.mdx @@ -25,15 +25,15 @@ Below it's the description in detail of all the upgrade steps and what which nod - 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 [3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3), with stop-slots, when this version becomes available + - 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 ([3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3)). 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` +**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 the new 32GB RAM requirement and support for _AVX_ and _BMI2_ CPU instructions. -1. Upgrade nodes to node version [3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3) ([3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3) has built-in stop slots). +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. @@ -41,15 +41,15 @@ Below it's the description in detail of all the upgrade steps and what which nod 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 [3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3). -3. Provision servers that meet the minimum hardware requirements, primarily the new 32GB RAM requirement. +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 [3.0.3](https://github.com/MinaProtocol/mina/releases/tag/3.0.3). -3. Provision servers that meet the minimum hardware requirements, particularly the new 32GB RAM requirement. +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_. *** @@ -83,7 +83,7 @@ Remember that although you might be able to submit transactions, the majority of ## 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/berkeley/docs/upgrading-to-berkeley.md) +- 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. @@ -109,7 +109,7 @@ There will be both Docker images and archive node releases available to choose f ## 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 Mina Foundation, helping monitor the network in the initial phase, please use the following flags when running your nodes: +- **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`