added initial draft for upgrade to mesa#1133
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
dkijania
force-pushed
the
dkijania/upgrade-to-mesa
branch
from
ccabdf6 to
b2ae3c9
Compare
| - 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. |
dkijania
force-pushed
the
dkijania/upgrade-to-mesa
branch
from
b2ae3c9 to
afa6095
Compare
dkijania
force-pushed
the
dkijania/upgrade-to-mesa
branch
from
afa6095 to
e19daf8
Compare
dkijania
force-pushed
the
dkijania/upgrade-to-mesa
branch
from
087520f to
9df874d
Compare
dkijania
force-pushed
the
dkijania/upgrade-to-mesa
branch
from
2dd75c4 to
3fac3ae
Compare
| ```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 |
There was a problem hiding this comment.
Same comment as Corvo's, I think pre-fork shoudl be 3.X.X
|
|
||
| <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> |
|
|
||
| **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. |
| ```bash | ||
| sudo systemctl stop mina | ||
| sudo apt-get update | ||
| sudo apt-get install mina-mainnet-mesa=<mesa-version> |
There was a problem hiding this comment.
Don't we know what this is at this point?
I've seen in a few places
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
|
|
||
| ```bash | ||
| sudo apt-get update | ||
| sudo apt-get install mina-mainnet-prefork-mesa=4.0.0 mina-mainnet-postfork-mesa=4.0.0 |
There was a problem hiding this comment.
Pre-fork package version incorrectly set to 4.0.0 instead of 3.3.0 (Berkeley version)
| |--|--|--|--|--| | ||
| | 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 | |
There was a problem hiding this comment.
32GB ram and 64GB storage per worker seems a bit high.
There was a problem hiding this comment.
Mesa SNARK Worker should be 6 core / 12 thread
There was a problem hiding this comment.
Addressed in 808427e — non-archive storage trimmed to 16 GB.
| | 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 | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Accepted. lowering ? 16 GB ?
There was a problem hiding this comment.
Addressed in 808427e — storage lowered to 16 GB for Mina Daemon, SNARK Coordinator and Seed; only archive-class nodes keep 64 GB.
|
|
||
| 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 |
There was a problem hiding this comment.
Could we point most of this list to other parts of the doc, in case people need more information?
There was a problem hiding this comment.
This comment contradict with one requesting removing page at all. Should i cherry pick useful information to the other parts or remove the page at all? which parts of the docs?
There was a problem hiding this comment.
Resolved by removing the page in fe443d1 rather than cherry-picking — the standalone-worker note already lives inline in upgrade-steps/index.mdx, and the rest duplicated Requirements.
dkijania
force-pushed
the
dkijania/upgrade-to-mesa
branch
from
8a09b07 to
79f6863
Compare
| - **Chain ID** matching the Mesa chain ID (`a7351abc7ddf2ea92d1b38cc8e636c271c1dfd2c081c637f62ebc2af34eb7cc1`) | ||
| - **Block height** advancing | ||
|
|
||
| #### 2. Verify block production |
There was a problem hiding this comment.
This should be removed and we just point to node-operators/block-producers section. So is most other stuff in this page on block producers. I'm sure that's the same situation for other couple of things here.
There was a problem hiding this comment.
Addressed in 555ac27 — block-production verification now points to /node-operators/block-producer-node instead of being inlined.
| mina internal snark-worker \ | ||
| --proof-level full \ | ||
| --shutdown-on-disconnect false \ | ||
| --daemon-address <coordinator-ip>:<port> |
There was a problem hiding this comment.
I haven't tested this(i.e. whether snark worker being compatible pre/post fork). I wasn't running a SNARK coordinator, could we find who actually run those in the dryrun and have them confirm the situation on this?
There was a problem hiding this comment.
I'm pretty sure they're going to be incompatible because the transaction snark changed. I was running a snark coordinator and worker in the company run; Luis was too, I want to say?
There was a problem hiding this comment.
Addressed in 555ac27 — documented that SNARK workers are incompatible across the fork (transaction SNARK changed) and must run a Mesa-compatible release after restart.
|
|
||
| # 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. This means all blocks produced during this period will be completely empty — no user commands, no coinbase rewards, and no fee transfers. The state finalization period ensures all nodes reach a consensus on the latest network state before the upgrade. |
There was a problem hiding this comment.
"transactions in them", not "transactions on them"
|
|
||
| 2. **Verify block production** — monitor that blocks are being produced at the expected cadence via block explorers and your node's logs. | ||
|
|
||
| 3. **Verify empty blocks during finalization** — confirm that all blocks between the _stop-transaction-slot_ and _stop-network-slot_ were empty (no user transactions, no coinbase, no fee transfers): |
There was a problem hiding this comment.
It's very unlikely, but we were discussing internally that this doesn't have to be the case - if you had a producer and archive operator who both forgot to upgrade to the stop slot release, then you could end up with a non-empty block after the stop tx slot. Might not be with mentioning.
There was a problem hiding this comment.
As long as most of the stake upgrades then such a block will be on a short fork and not affect the hard fork block anyway, so it's not a problem for the fork that this might happen.
There was a problem hiding this comment.
Addressed in 555ac27 — added a note that a non-empty block can appear after the stop-transaction-slot if a producer and archive both skip the stop-slot release, but it lands on a short fork and doesn't affect the hard fork when most stake upgraded.
| For full details, see the [Mesa release notes](https://github.com/MinaProtocol/mina/releases?q=mesa). {/* TODO(PR #1133): Replace with the specific Mesa release tag URL once published (e.g. `/releases/tag/4.0.0`). */} | ||
|
|
||
| :::info What changed in Mesa | ||
| - **`--hardfork-handling` should no longer be set.** This Berkeley-era flag selected how the daemon should behave around fork boundaries. The Mesa binary still parses it (so passing it will not crash the daemon), but the flag has no effect post-fork: once you are running on the Mesa chain there is no hardfork left to handle. Fork handling now lives in the automode dispatcher (for automode) or in the operator's explicit stop/install/restart procedure (for manual mode). Remove `--hardfork-handling` from your startup config, systemd unit, Docker command, or Helm values when you move to the Mesa release so it does not mask a real configuration mistake later. |
There was a problem hiding this comment.
This flag is still recognized by the daemon, right? It's just that users don't have to enable it themselves. It was only developed after the Berkeley hard fork too. Maybe consider removing?
There was a problem hiding this comment.
Yes, that's why i added "should no longer be set" . but i can remove it as well
There was a problem hiding this comment.
Addressed in 555ac27 — removed the --hardfork-handling bullet from the 'What changed in Mesa' callout entirely.
|
|
||
| :::info What changed in Mesa | ||
| - **`--hardfork-handling` should no longer be set.** This Berkeley-era flag selected how the daemon should behave around fork boundaries. The Mesa binary still parses it (so passing it will not crash the daemon), but the flag has no effect post-fork: once you are running on the Mesa chain there is no hardfork left to handle. Fork handling now lives in the automode dispatcher (for automode) or in the operator's explicit stop/install/restart procedure (for manual mode). Remove `--hardfork-handling` from your startup config, systemd unit, Docker command, or Helm values when you move to the Mesa release so it does not mask a real configuration mistake later. | ||
| - **If you used manual mode, repoint `--genesis-ledger-dir` and `-config-file` at the Mesa-specific files.** Both ship inside the Mesa Debian/Docker package: `--genesis-ledger-dir` should be `/var/lib/coda/mesa` (or the equivalent path your package installed), and `-config-file` should be the Mesa runtime config (typically `/etc/mina/mesa/daemon.json`). Automode users do not need to do this — the dispatcher rewrites both arguments automatically. |
There was a problem hiding this comment.
Users relying on the installed genesis config shouldn't need to do this. Might want to clarify that users who manually manage their genesis config and/or genesis ledgers will need to do this.
There was a problem hiding this comment.
Addressed in 555ac27 — clarified that repointing --genesis-ledger-dir / -config-file is only for operators who manually manage their genesis config/ledgers; package and automode users don't need to.
|
|
||
| ### Mesa Genesis Timestamp | ||
|
|
||
| The predefined time at which the first block is produced on the new Mesa chain — exactly 3 hours after the Mesa release is published. This marks the start of the upgraded network. |
There was a problem hiding this comment.
Exactly 3 hours after the network stop slot
There was a problem hiding this comment.
Follow-up: made the genesis-timestamp wording consistent everywhere (index, fork-schedule, examples now also say "3 hours after the stop-network-slot") in b25e28f.
|
|
||
| --- | ||
|
|
||
| ## Mesa-Specific Changes and Conventions |
There was a problem hiding this comment.
Not strictly necessary, but could mention the other MIPS here too
There was a problem hiding this comment.
I'm not sure how it's happening, but I think this page is being rendered in the breadcrumb path "Home > Network Upgrades > Mesa Upgrades > Appendix > Appendix" in the deployed docs I'm looking at. Maybe it's because the "Upgrade Modes - Details" and "Docker Compose Quickstart" are this page's siblings? Not critical, just a little weird.
There was a problem hiding this comment.
Accepted. will fix page structure
There was a problem hiding this comment.
Fixed in 9456f80 — the appendix pages now live under an appendix/ subfolder (archive-node-schema-changes, upgrade-modes-details, automode-docker-compose-quickstart), so the breadcrumb reads e.g. 'Appendix > Archive Node Schema Changes' instead of 'Appendix > Appendix'.
There was a problem hiding this comment.
Nobody care if we're putting into efforts, suggest delete this statement as it's just noise.
There was a problem hiding this comment.
Accepted. will remove it
There was a problem hiding this comment.
Addressed in cac8100 — removed the filler sentence (also renamed the schema-version table to migration_history across this page to match the actual schema).
| ### Building from Source | ||
|
|
||
| ```bash | ||
| dune build src/app/replayer/replayer.exe --profile=dev |
There was a problem hiding this comment.
Why is it even here? building mina requires setting up a lot of environment and our engs are literally having trouble to set it up on our local machine. Why not just have a debian/docker instruction?
There was a problem hiding this comment.
Addressed in 11cbbe9 — replaced the build-from-source instructions with how to get mina-replayer from the archive Debian package / Docker image.
| - quickstart | ||
| --- | ||
|
|
||
| # Docker Compose Quickstart |
There was a problem hiding this comment.
Might want to emphasize that this is an auto mode example in the title
There was a problem hiding this comment.
Done in 9456f80 — title is now 'Automode Docker Compose Quickstart'.
| --peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt \ | ||
| --insecure-rest-server \ | ||
| --rest-port 3085 \ | ||
| --hardfork-handling migrate-exit |
There was a problem hiding this comment.
Did we get rid of the requirement to pass this flag in the auto mode packaging?
There was a problem hiding this comment.
It's different approach. Operator need to provide this flag but we are removing it when using mesa runtime, so user does not need to have logic like :
if berkeley then
"--hardfork-handling migrate-exit"
else
""
``
We does not allow this parameter on mesa version when using dispatcher
There was a problem hiding this comment.
Captured in 9456f80 — added an ':::tip About --hardfork-handling' on the page explaining that you always pass the flag on the automode image and the dispatcher consumes it, so no conditional logic is needed.
| items: [ | ||
| 'network-upgrades/mesa/appendix', | ||
| 'network-upgrades/mesa/upgrade-modes-details', | ||
| 'network-upgrades/mesa/docker-compose-quickstart', |
There was a problem hiding this comment.
for this one specifically we agreed on network-upgrades/mesa/appendix/automode-docker-compose-quickstart
There was a problem hiding this comment.
Done in 9456f80 — the page is now network-upgrades/mesa/appendix/automode-docker-compose-quickstart.
Addresses review comment r3277656351. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Mesa Genesis Timestamp is 3h after the stop-network-slot, not after release publication (r3277800577). - Add brief Faster Blocks / Larger Events & Actions / Larger zkApp Transactions entries (MIP6/8/9) to Mesa-Specific Changes (r3277825150). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Storage 64 GB -> 16 GB for Mina Daemon, SNARK Coordinator, Seed (only archive-class nodes need 64 GB) (r2969366715, r2966094903). - Anchor networking link to #networking (r3270987988). - Point libp2p key link to /node-operators/seed-peers/generating-a-libp2p-keypair instead of the wallet-keypair page (r3270991798). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The docker-compose quickstart is automode-only, so it doesn't belong in the Manual Mode instructions (r3271028782). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…story - Drop the "we put all efforts..." filler sentence (r3278596532). - Rename the version table to migration_history across archive-upgrade.mdx (prose, rollback note, verification query) to match the actual schema. - Update the appendix table definition to migration_history with its real column set. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The deposit/withdrawal instruction duplicated state-finalization.mdx and the post-release upgrade step is covered on the post-upgrade page (r3271499535). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Consolidate the repeated "confirm on Mesa chain" status check into one shared block (r3055561321). - Chain ID is network-specific and published with the release; drop the hardcoded mainnet chain ID; add Git SHA-1 and genesis-timestamp checks (r3271508236). - Point block-production verification to /node-operators/block-producer-node instead of inlining it (r3271512635). - SNARK workers are incompatible across the fork; document redeploy and the full mesa binary path (mina-mesa not on PATH in Docker) (r3271522639, r3055558562). - Tab-ify In-Depth Validation (r3271505182). - Note that a non-empty post-stop-slot block is possible but lands on a short fork (r3277705581). - Remove the --hardfork-handling bullet (r3277741989); clarify --genesis-ledger-dir is only for manual genesis management (r3277752220). - Align genesis timing wording with the glossary; rename version table to migration_history. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Pre-Upgrade page duplicated the Requirements page (agreed with reviewers). Delete it, drop its sidebar entry, remove the legacy redirect, and repoint inbound links in index.mdx, upgrade-steps/index.mdx and examples.mdx to Requirements. (r3271127365, r3271069017, r3271070471, r3271076240, r3271085351, r3271081259, r3199028680, r2969370024) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per reviewer agreement, group the three appendix docs under a real appendix/ subfolder so IDs are network-upgrades/mesa/appendix/<page> and the breadcrumb no longer reads "Appendix > Appendix": - appendix.mdx -> appendix/archive-node-schema-changes.mdx - upgrade-modes-details.mdx -> appendix/upgrade-modes-details.mdx - docker-compose-quickstart.mdx -> appendix/automode-docker-compose-quickstart.mdx Update sidebars.js, repoint all inbound links (anchors preserved), add redirects for the old paths, and document the --hardfork-handling flag on the automode compose page. (r3277849899, r3282844950, r3282849145, r3230094542, r3228596882, r3281405586, r3281411586, r2969369017) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The replayer is a general archive tool, not Mesa-specific (r3198983919), so move it under node-operators/archive-node/ and rewrite it as standalone documentation: general usage first, with all hard-fork material in one supplementary section at the bottom. Also replace the build-from-source instructions with Debian/Docker install guidance (r3278614586). - git mv network-upgrades/mesa/replayer.mdx -> node-operators/archive-node/replayer.mdx - move sidebar entry to the Archive Nodes category - repoint inbound links (archive-upgrade.mdx, glossary.mdx) and add a redirect Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- glossary: link to the Mesa overview at its folder URL, not /index - index: point the "which binary" Troubleshooting link to the troubleshooting page where that anchor lives - fork-schedule: drop the non-existent upgrade-modes#manual-mode anchor Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
cjjdespres confirmed (and the author accepted) that the genesis timestamp is 3 hours after the stop-network-slot, not after release publication. Make the remaining mentions in index.mdx, fork-schedule.mdx and examples.mdx consistent with the glossary and post-upgrade pages (r3277800577). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
cjjdespres noted this flag does nothing; remove it from the Block Producer and Archive Node flag references (r3220687330). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reflects the second-round Mesa review fixes: removed Pre-Upgrade page, appendix restructure, relocated Archive Replayer, and the various content edits across the Mesa upgrade docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Second review round — fixes (after #issuecomment-4482810711)Worked through the post-summary review remarks from @cjjdespres and @glyh (plus @glyh's flagged-unresolved list), one logical change per commit. Each thread has an individual reply linking its commit; the table below is the overview.
Validation: @glyh — your flagged-unresolved list (#issuecomment-4494118429) is fully addressed (r2969366715, r2969370024, r3055558562, r3055561321 fixed; r3198908301 is outdated — the grid no longer embeds Debian-only install steps). A few earlier-round threads remain as documented TODOs depending on inputs outside this PR (concrete Mesa mainnet version/fork-schedule numbers, the o1js upgrade-guide link, canonical MIP list, release-tag URLs). Please re-check the threads you each filed. |
7 participants
No description provided.