added initial draft for upgrade to mesa by dkijania · Pull Request #1133 · MinaProtocol/docs2

dkijania · 2025-09-10T14:20:31Z

No description provided.

vercel · 2025-09-10T14:20:36Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs2	Ready	Preview, Comment	Mar 20, 2026 4:56pm

glyh · 2025-11-30T03:43:08Z

docs/mesa-upgrade/appendix.mdx

+
+Below we presents details what was changed in the archive node database schema between Berkeley and Mesa version.
+
+**Zkapp_state_nullable additional Columns **


This is not complete. we also updated the non-nullable table.

glyh · 2025-11-30T03:44:06Z

docs/mesa-upgrade/appendix.mdx

+
+```
+
+**Version table**


This is wrong. if you look at current codebase.

cjjdespres · 2025-12-03T21:49:49Z

docs/mesa-upgrade/upgrade-steps.mdx

+    - 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.


Is this still true?

no, good catch

yamimaio · 2025-12-11T12:42:55Z

docs/mesa-upgrade/flags-configs.mdx

+hide_title: true
+description: Post-Upgrade Flags and Configurations for Mainnet
+keywords:
+  - Berkeley


should this be Berkeley or Mesa?

yamimaio · 2025-12-11T12:43:49Z

docs/mesa-upgrade/flags-configs.mdx

+
+# 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).


Should this be Berkeley?

yamimaio · 2025-12-11T12:44:55Z

docs/mesa-upgrade/requirements.mdx

+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.


yamimaio · 2025-12-11T12:45:07Z

docs/mesa-upgrade/requirements.mdx

+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


yamimaio · 2025-12-11T12:48:05Z

docs/mesa-upgrade/requirements.mdx

+
+:::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`.


is this the right version?

yamimaio · 2025-12-11T12:52:54Z

docs/mesa-upgrade/upgrade-steps.mdx

+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).


version will need to change

yamimaio · 2025-12-11T12:53:07Z

docs/mesa-upgrade/upgrade-steps.mdx

+  - 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.


Ram requirement is not new

yamimaio · 2025-12-11T12:53:29Z

docs/mesa-upgrade/upgrade-steps.mdx

+### 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).


Version needs to change

yamimaio · 2025-12-11T12:54:35Z

docs/mesa-upgrade/upgrade-steps.mdx

+## 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)


link needs to change

yamimaio · 2025-12-11T12:55:34Z

docs/mesa-upgrade/upgrade-steps.mdx

+## 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:


errors should be reported to us, not to MF

Delete legacy docs paths (docs/berkeley-upgrade/, docs/mesa-upgrade/) that have been superseded by the unified docs/network-upgrades/ structure. Update docusaurus config, dependencies, and checklist styles. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Restructure the Mesa upgrade index page with: - End-to-end upgrade timeline with visual overview and milestone table - Per-phase breakdowns (pre-upgrade, state finalization, upgrade, post-upgrade) with actor-specific action tables - Collapsible role-based timeline views with schedule images - Upgrade mode summary (automode vs manual) with dispatcher limitation notes - Six collapsible walk-through examples covering all roles: - Block Producer automode (Debian), manual (Docker), manual (Debian) - Archive Node / Explorer operator - zkApp Developer - Exchange operator - Quick reference table linking each operator type to relevant pages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Document the automode and manual upgrade mechanisms in depth: - Dispatcher limitations: only supports daemon subcommand, explained why (no config dir context for non-daemon commands), with guidance to use mina-berkeley/mina-mesa binaries directly - Automode restart mechanism: daemon exits with code 0, requires process manager restart (systemd/Docker/k8s) and persistent filesystem for the activated marker file - Correct activation file path: auto-fork-mesa-mainnet/activated - Professional SVG flowcharts replacing ASCII timelines for both automode and manual upgrade flows - Kubernetes/Helm-specific guidance on PersistentVolumeClaim vs emptyDir and restart policies Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace the flag-heavy post-upgrade page with an actionable guide: - Tabbed per-role verification steps (Block Producer, SNARK, Archive, Rosetta, Exchange) with concrete commands - Merged the standalone validation page into an in-depth validation section covering daemon, archive toolbox, Rosetta CLI, and network-level checks - Flags and configurations moved to a collapsed reference section with a note that they are unchanged from Berkeley - Node Status service opt-in instructions for network monitoring Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Make the Archive Upgrade a sidebar category with the Archive Replayer as its child page. Add a bridging section in archive-upgrade.mdx that introduces the replayer as an ongoing verification tool (not limited to upgrade time). Update replayer description to emphasize its role as a continuous archive integrity tool. Remove standalone validation page from sidebar (merged into post-upgrade). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Move Berkeley upgrade documentation to docs/network-upgrades/berkeley/ and add the network-upgrades landing page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

glyh · 2026-03-17T09:47:33Z

docs/network-upgrades/mesa/upgrade-steps/index.mdx

+
+docker run --name mina -d \
+  -v mina-config:/root/.mina-config \
+  minaprotocol/mina-daemon:4.0.0-bullseye-mainnet \


Why is the pre-fork image 4.0.0? Shouldn't it be tagged 3.x.x, pointing to the RC?

oh right, stop slot release would still have 3.xx

glyh · 2026-03-17T09:48:51Z

docs/network-upgrades/mesa/upgrade-steps/index.mdx

+
+### Archive Node Operator
+
+Archive nodes do **not** support automode — they always require manual steps. You also need to handle the database migration.


I thought what we said is just upgrade the schema prefork and run post-fork archive and everything should work as expected, does that changed?

I will reword it, yes. Let's avoid using migration term, it's just simple upgrade

yamimaio · 2026-03-19T22:59:09Z

docs/network-upgrades/mesa/upgrade-steps/index.mdx

+```bash
+# Pre-Upgrade: install both automode packages
+sudo apt-get update
+sudo apt-get install mina-mainnet-prefork-mesa=4.0.0 mina-mainnet-postfork-mesa=4.0.0


Same comment as Corvo's, I think pre-fork shoudl be 3.X.X

yamimaio · 2026-03-19T23:14:08Z

docs/network-upgrades/mesa/upgrade-steps/pre-upgrade.mdx

+
+<ul className="checklist">
+  <li>Chosen an <a href="/network-upgrades/mesa/upgrade-modes">upgrade mode</a>: automode (recommended) or manual</li>
+  <li>Upgraded node to the current stable version (3.3.0)</li>


This probably won't be it. I think it's already not it, right?

yamimaio · 2026-03-19T23:15:45Z

docs/network-upgrades/mesa/upgrade-steps/pre-upgrade.mdx

+
+<ul className="checklist">
+  <li>Chosen an <a href="/network-upgrades/mesa/upgrade-modes">upgrade mode</a>: automode (recommended) or manual</li>
+  <li>Upgraded node to the current stable version (3.3.0)</li>


yamimaio · 2026-03-19T23:16:51Z

docs/network-upgrades/mesa/upgrade-steps/pre-upgrade.mdx

+#### Software Upgrade
+
+<ul className="checklist">
+  <li>Upgraded node to the current stable version (3.3.0)</li>


yamimaio · 2026-03-19T23:17:26Z

docs/network-upgrades/mesa/upgrade-steps/pre-upgrade.mdx

+#### Software Upgrade
+
+<ul className="checklist">
+  <li>Upgraded node to the current stable version (3.3.0)</li>


yamimaio · 2026-03-19T23:38:04Z

docs/network-upgrades/mesa/index.mdx

+<details>
+<summary><b>Example: zkApp Developer</b></summary>
+
+**Frank** maintains a zkApp deployed on mainnet. His contract uses on-chain state and he wants to take advantage of Mesa's expanded 31-field state.


yamimaio · 2026-03-19T23:38:38Z

docs/network-upgrades/mesa/index.mdx

+He verifies that:
+- His existing zkApp (compiled for Berkeley) still works unchanged on the preflight Mesa network
+- Transactions deploy and execute correctly
+- If he plans to use the expanded state fields (9–31), his new contract version compiles and deploys on preflight


yamimaio · 2026-03-19T23:40:34Z

docs/network-upgrades/mesa/index.mdx

+
+**Hours before the fork (State Finalization)** — Frank does **nothing**. His deployed zkApp keeps running on the Berkeley chain. No transactions can be submitted during this phase anyway.
+
+**Fork day (Upgrade)** — Frank does **nothing**. His existing zkApp state carries over to the Mesa chain automatically. All account state (including zkApp state fields 1–8) is preserved exactly as-is.


is it 1-8 or 0-7?

yamimaio · 2026-03-19T23:41:34Z

docs/network-upgrades/mesa/index.mdx

+zkapp deploy --network mainnet
+```
+
+If his zkApp does not need the new state fields, no redeployment is needed — it continues to work on Mesa without changes.


is this true? don't all apps need to be redeployed?

yamimaio · 2026-03-19T23:43:57Z

docs/network-upgrades/mesa/index.mdx

+```bash
+sudo systemctl stop mina
+sudo apt-get update
+sudo apt-get install mina-mainnet-mesa=<mesa-version>


Don't we know what this is at this point?
I've seen in a few places

glyh · 2026-03-20T07:05:37Z

docs/network-upgrades/mesa/upgrade-steps/index.mdx

+sudo systemctl stop mina
+
+sudo apt-get update
+sudo apt-get install mina-mainnet-mesa=<mesa-version>


The tagging scheme is a bit confusing to me. Why is it necessary to have a -mesa in the package name? Isn't 4.x.x enough to indicate this is a mesa package?

vercel · 2026-03-20T10:33:23Z

docs/network-upgrades/mesa/index.mdx

+
+```bash
+sudo apt-get update
+sudo apt-get install mina-mainnet-prefork-mesa=4.0.0 mina-mainnet-postfork-mesa=4.0.0


Pre-fork package version incorrectly set to 4.0.0 instead of 3.3.0 (Berkeley version)

vercel · 2026-03-20T10:33:23Z

docs/network-upgrades/mesa/index.mdx

+
+### Expanded zkApp State
+
+Mesa extends the on-chain state available to zkApps from 8 fields to 31 fields per account. This significantly increases the data capacity available to smart contracts, enabling more complex application logic without off-chain workarounds.


Field count documentation incorrectly states 31 fields total when Mesa actually extends to 32 fields (element0 through element31)

vercel · 2026-03-20T10:33:23Z

docs/network-upgrades/mesa/upgrade-steps/index.mdx

+```bash
+# Pre-Upgrade: install both automode packages
+sudo apt-get update
+sudo apt-get install mina-mainnet-prefork-mesa=4.0.0 mina-mainnet-postfork-mesa=4.0.0


Pre-fork Mesa package incorrectly specified as 4.0.0 instead of 3.3.0 (pre-fork stable version)

vercel · 2026-03-20T10:33:23Z

docs/network-upgrades/mesa/upgrade-steps/index.mdx

+sudo systemctl stop mina
+
+sudo apt-get update
+sudo apt-get install mina-mainnet-mesa=<mesa-version>


Suggested change

sudo apt-get install mina-mainnet-mesa=<mesa-version>

sudo apt-get install mina-mainnet-mesa=4.0.0

Debian example uses placeholder <mesa-version> while Docker example uses concrete version 4.0.0-bullseye-mesa, causing inconsistency in documentation examples

cjjdespres · 2026-03-20T14:28:48Z

docs/network-upgrades/mesa/requirements.mdx

+|--|--|--|--|--|
+| 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 |


32GB ram and 64GB storage per worker seems a bit high.

glyh · 2026-03-21T09:17:11Z

docs/network-upgrades/mesa/requirements.mdx

+| 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 |


To add to Chrstian's comment, it doesn't make sense to me for any node other than archive to have a 64GB storage requirement -- There's nothing growing linearly, and should not be, right?

I guess, logs could grow, but still 64GB seems too big.

glyh · 2026-03-21T09:17:42Z

docs/network-upgrades/mesa/requirements.mdx

+
+:::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`.


Why installing new package couldn't auto remove the old?

glyh · 2026-03-21T09:20:10Z

docs/network-upgrades/mesa/upgrade-modes-details.mdx

@@ -0,0 +1,305 @@
+---


Do people actually care this doc?

glyh · 2026-03-21T09:21:19Z

docs/network-upgrades/mesa/upgrade-steps/pre-upgrade.mdx

+
+During the Pre-Upgrade phase, node operators prepare their infrastructure for the Mesa hard fork. Select your role below and work through each item on the checklist.
+
+## Readiness Checklist


Could we point most of this list to other parts of the doc, in case people need more information?

dkijania force-pushed the dkijania/upgrade-to-mesa branch from ccabdf6 to b2ae3c9 Compare November 27, 2025 22:17

vercel bot deployed to Preview – docs2 November 27, 2025 22:19 View deployment

glyh reviewed Nov 30, 2025

View reviewed changes

cjjdespres reviewed Dec 3, 2025

View reviewed changes

dkijania force-pushed the dkijania/upgrade-to-mesa branch from b2ae3c9 to afa6095 Compare December 11, 2025 10:44

vercel bot deployed to Preview – docs2 December 11, 2025 10:45 View deployment

dkijania force-pushed the dkijania/upgrade-to-mesa branch from afa6095 to e19daf8 Compare December 11, 2025 12:02

dkijania marked this pull request as ready for review December 11, 2025 12:03

vercel bot deployed to Preview – docs2 December 11, 2025 12:03 View deployment

yamimaio reviewed Dec 11, 2025

View reviewed changes

vercel bot deployed to Preview – docs2 December 13, 2025 19:23 View deployment

dkijania force-pushed the dkijania/upgrade-to-mesa branch from 087520f to 9df874d Compare March 13, 2026 19:51

vercel bot deployed to Preview – docs2 March 13, 2026 19:52 View deployment

vercel bot had a problem deploying to Preview – docs2 March 15, 2026 19:44 Failure

dkijania and others added 6 commits March 15, 2026 20:46

Add Berkeley upgrade docs and network-upgrades index under new path

3fac3ae

Move Berkeley upgrade documentation to docs/network-upgrades/berkeley/ and add the network-upgrades landing page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

dkijania force-pushed the dkijania/upgrade-to-mesa branch from 2dd75c4 to 3fac3ae Compare March 15, 2026 19:47

vercel bot had a problem deploying to Preview – docs2 March 15, 2026 19:48 Failure

glyh reviewed Mar 17, 2026

View reviewed changes

yamimaio reviewed Mar 19, 2026

View reviewed changes

glyh reviewed Mar 20, 2026

View reviewed changes

vercel bot reviewed Mar 20, 2026

View reviewed changes

cjjdespres reviewed Mar 20, 2026

View reviewed changes

commenting out invalid redirect target so that build can succeed

8a09b07

vercel bot deployed to Preview – docs2 March 20, 2026 16:56 View deployment

glyh reviewed Mar 21, 2026

View reviewed changes

docs/network-upgrades/mesa/upgrade-modes-details.mdx

@@ -0,0 +1,305 @@

---

Copy link

Member

glyh Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do people actually care this doc?

glyh reviewed Mar 21, 2026

View reviewed changes


		Below we presents details what was changed in the archive node database schema between Berkeley and Mesa version.

		Zkapp_state_nullable additional Columns


		# 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).


		:::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`.


		### Archive Node Operator

		Archive nodes do not support automode — they always require manual steps. You also need to handle the database migration.


		Hours before the fork (State Finalization) — Frank does nothing. His deployed zkApp keeps running on the Berkeley chain. No transactions can be submitted during this phase anyway.

		Fork day (Upgrade) — Frank does nothing. His existing zkApp state carries over to the Mesa chain automatically. All account state (including zkApp state fields 1–8) is preserved exactly as-is.


		### Expanded zkApp State

		Mesa extends the on-chain state available to zkApps from 8 fields to 31 fields per account. This significantly increases the data capacity available to smart contracts, enabling more complex application logic without off-chain workarounds.

	sudo apt-get install mina-mainnet-mesa=<mesa-version>
	sudo apt-get install mina-mainnet-mesa=4.0.0


		During the Pre-Upgrade phase, node operators prepare their infrastructure for the Mesa hard fork. Select your role below and work through each item on the checklist.

		## Readiness Checklist


		```

		Version table

Conversation

dkijania commented Sep 10, 2025

Uh oh!

vercel bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glyh Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glyh Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vercel bot Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

vercel bot Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

vercel bot Mar 20, 2026

Choose a reason for hiding this comment

vercel bot commented Sep 10, 2025 •

edited

Loading

glyh Mar 17, 2026 •

edited

Loading

glyh Mar 20, 2026 •

edited

Loading