diff --git a/docs/network-upgrades/index.mdx b/docs/network-upgrades/index.mdx index e533ec5a6..411e135f1 100644 --- a/docs/network-upgrades/index.mdx +++ b/docs/network-upgrades/index.mdx @@ -15,15 +15,9 @@ keywords: Mina Protocol evolves through network upgrades (hard forks). Each upgrade introduces new protocol features, performance improvements, or governance changes. Hard forks are not backward compatible — all node operators must upgrade before the fork activates. -:::tip Mesa preflight hard fork completed +:::tip Mesa preflight update -The Mesa preflight network hard-forked at **2026-04-27 13:00 UTC**. The post-fork chain is now running the Mesa release **`4.0.0-preflight-3f038cb`**, which raises the **transaction protocol version to 5.0.0**. - -Operators must run **`4.0.0-preflight-3f038cb`** to remain on the preflight network. Earlier builds — including the stop-slot release `4.0.0-preflight-stop-2967b39` — are no longer compatible with the post-fork chain. - -zkApp developers must update to **`o1js@3.0.0-mesa.698ca`**, which targets transaction protocol v5.0.0; earlier o1js releases will produce transactions that the post-fork network rejects. - -See [Preflight Network](/network-upgrades/mesa/preflight-network) for the full upgrade path. +The Mesa preflight network hard fork completed on **2026-04-27 13:00 UTC**. See [Preflight Network](/network-upgrades/mesa/preflight-network) for the current build versions and upgrade path. ::: diff --git a/docs/network-upgrades/mesa/archive-upgrade.mdx b/docs/network-upgrades/mesa/archive-upgrade.mdx index 15977c2d0..5bebfb311 100644 --- a/docs/network-upgrades/mesa/archive-upgrade.mdx +++ b/docs/network-upgrades/mesa/archive-upgrade.mdx @@ -11,26 +11,51 @@ keywords: - archive node --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Archive Upgrade This guide describes the general procedure for upgrading a Mina archive database from Berkeley to Mesa. The same steps apply to every Mesa deployment (preflight, devnet, mainnet) — only the archive package version differs. -:::tip Mesa preflight hard fork completed - -The Mesa preflight network hard-forked at **2026-04-27 13:00 UTC**. The post-fork chain runs **`4.0.0-preflight-3f038cb`**, which raises the **transaction protocol version to 5.0.0**. Pre-fork builds — including the stop-slot release `4.0.0-preflight-stop-2967b39` — are no longer compatible. +:::tip Preflight-specific version info -When upgrading a preflight archive database, install the matching `mina-archive-mesa=4.0.0-preflight-3f038cb` package so the archive node speaks the new transaction protocol. +The Mesa preflight network has already forked. See [Preflight Network](/network-upgrades/mesa/preflight-network) for the current build versions and transaction protocol details. ::: -:::info Choosing the Mesa archive version + + + +The preflight archive version is **`4.0.0-preflight-3f038cb`** (post-hard-fork; transaction protocol v5.0.0). Docker tag: `gcr.io/o1labs-192920/mina-archive:4.0.0-preflight-3f038cb-bookworm-mesa`. See [Preflight Network](./preflight-network) for the full release matrix. + +```bash +# Substitute this version wherever appears below +MESA_VERSION=4.0.0-preflight-3f038cb +``` -The commands below use `` as a placeholder for the archive build you want to install. Substitute the tag that matches your target network: + + -- **Preflight network** — use `4.0.0-preflight-3f038cb` (post-hard-fork; transaction protocol v5.0.0). See [Preflight Network](./preflight-network) for the full release matrix. -- **Devnet / mainnet** — use the Mesa release tag published for that network when it is announced. +The devnet Mesa archive version will be published when the devnet fork is scheduled. Check [Mina releases](https://github.com/MinaProtocol/mina/releases?q=mesa) for the latest tag. -::: +```bash +# Substitute this version wherever appears below +MESA_VERSION= +``` + + + + +The mainnet Mesa archive version will be published in the Mesa release announcement. Check [Mina releases](https://github.com/MinaProtocol/mina/releases?q=mesa) for the `4.x.x` tag. + +```bash +# Substitute this version wherever appears below +MESA_VERSION= +``` + + + To successfully upgrade the archive database to Mesa, you must ensure that your environment meets the foundational requirements. @@ -43,7 +68,7 @@ To successfully upgrade the archive database to Mesa, you must ensure that your ## Archive database -One of the most obvious prerequisites is a Mainnet database. If you don't have an existing database with Devnet/Mainnet archive data, +One of the most obvious prerequisites is an archive database with Berkeley-era data. If you don't have an existing database with Devnet or Mainnet archive data, you can always download it from the O1Labs Google Cloud bucket. ## Upgrade process diff --git a/docs/network-upgrades/mesa/fork-schedule.mdx b/docs/network-upgrades/mesa/fork-schedule.mdx index 326a3b17b..3b40133a2 100644 --- a/docs/network-upgrades/mesa/fork-schedule.mdx +++ b/docs/network-upgrades/mesa/fork-schedule.mdx @@ -29,14 +29,14 @@ The relevant moments are: The mainnet Mesa fork schedule has not been announced. The values below are placeholders. They will be filled in once o1Labs publishes the stop-slot release and the Mesa genesis timestamp. ::: -| Field | Value | -|---|---| -| Pre-fork (stop-slot) release | _TBD — will be a `3.x.x` tag_ | -| Mesa release | _TBD — will be a `4.x.x` tag_ | -| `stop-transaction-slot` (`slot_tx_end`) | _TBD_ | -| `stop-network-slot` (`slot_chain_end`) | _TBD_ | -| Mesa genesis timestamp (UTC) | _TBD — exactly 3 hours after the stop-network-slot_ | -| State Finalization window | Exactly 100 slots = exactly 5 hours between `slot_tx_end` and `slot_chain_end` | +| Field | Value | +| --------------------------------------- | ------------------------------------------------------------------------------ | +| Pre-fork (stop-slot) release | _TBD — will be a `3.x.x` tag_ | +| Mesa release | _TBD — will be a `4.x.x` tag_ | +| `stop-transaction-slot` (`slot_tx_end`) | _TBD_ | +| `stop-network-slot` (`slot_chain_end`) | _TBD_ | +| Mesa genesis timestamp (UTC) | _TBD — exactly 3 hours after the stop-network-slot_ | +| State Finalization window | Exactly 100 slots = exactly 5 hours between `slot_tx_end` and `slot_chain_end` | Subscribe to the [MinaProtocol/mina releases](https://github.com/MinaProtocol/mina/releases?q=mesa) and watch the [Mina Foundation announcements channel](https://discord.gg/minaprotocol) for the schedule publication. @@ -46,26 +46,26 @@ Subscribe to the [MinaProtocol/mina releases](https://github.com/MinaProtocol/mi Devnet typically forks ahead of mainnet to give integrators a final dress rehearsal. Schedule will be posted here once announced. ::: -| Field | Value | -|---|---| -| Pre-fork (stop-slot) release | _TBD_ | -| Mesa release | _TBD_ | +| Field | Value | +| --------------------------------------- | ----- | +| Pre-fork (stop-slot) release | _TBD_ | +| Mesa release | _TBD_ | | `stop-transaction-slot` (`slot_tx_end`) | _TBD_ | -| `stop-network-slot` (`slot_chain_end`) | _TBD_ | -| Mesa genesis timestamp (UTC) | _TBD_ | +| `stop-network-slot` (`slot_chain_end`) | _TBD_ | +| Mesa genesis timestamp (UTC) | _TBD_ | ## Preflight The Mesa preflight network has already forked. The numbers below are historical; they will not change. -| Field | Value | -|---|---| -| Pre-fork release | `4.0.0-preflight1-b649c79` | -| Stop-slot release | `4.0.0-preflight-stop-2967b39` | -| Mesa release | `4.0.0-preflight-3f038cb` | -| Mesa hard-fork time (UTC) | 2026-04-27 13:00 | -| Transaction protocol version after fork | 5.0.0 | -| o1js version targeting protocol v5.0.0 | `o1js@3.0.0-mesa.698ca` | +| Field | Value | +| --------------------------------------- | ------------------------------ | +| Pre-fork release | `4.0.0-preflight1-b649c79` | +| Stop-slot release | `4.0.0-preflight-stop-2967b39` | +| Mesa release | `4.0.0-preflight-3f038cb` | +| Mesa hard-fork time (UTC) | 2026-04-27 13:00 | +| Transaction protocol version after fork | 5.0.0 | +| o1js version targeting protocol v5.0.0 | `o1js@3.0.0-mesa.698ca` | For the full preflight context, see [Preflight Network](/network-upgrades/mesa/preflight-network). diff --git a/docs/network-upgrades/mesa/glossary.mdx b/docs/network-upgrades/mesa/glossary.mdx index f55ab7afb..3b296af79 100644 --- a/docs/network-upgrades/mesa/glossary.mdx +++ b/docs/network-upgrades/mesa/glossary.mdx @@ -120,23 +120,34 @@ The official ledger checkpoint published with the [Mesa release](#mesa-release). ## Mesa-Specific Changes and Conventions -Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavior. Full descriptions live in the [Mesa overview](/network-upgrades/mesa#what-mesa-introduces); the brief definitions below link each to its canonical spec. +Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavior. The canonical MIP specs live in the [MinaProtocol/MIPs](https://github.com/MinaProtocol/MIPs/tree/main/MIPS) repository; each section below links to the spec for the proposal it describes. -### Faster Blocks +### Faster Blocks — [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md) -Mesa reduces the slot time to 90 seconds and unsets the default zkApp soft limit (previously 24 commands per block). Defined in [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md). +Mesa halves Mina's slot time from **180 seconds to 90 seconds**, doubling block production frequency. To keep the long-term token emission rate flat, the per-block **coinbase reward is also halved** (from 720 MINA to 360 MINA). The total Mina supplied per epoch is unchanged. -### Expanded zkApp State +Several second-order consequences flow from the slot-time change: -Mesa increases the on-chain state available to zkApps from 8 fields (indexes `0–7`) to 32 fields (indexes `0–31`) per account. This applies to both the `zkapp_states` and `zkapp_states_nullable` database tables. Defined in [MIP7](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0007-increase-state-size-limit.md). See [Archive Node Schema Changes](/network-upgrades/mesa/appendix/archive-node-schema-changes) for the SQL diff. +- **Epoch duration halves** from ~14.9 days to ~7.4 days. Scripts and operational procedures tied to epoch boundaries (delegation cooldown, automated payouts, monitoring dashboards) trigger about twice as often. +- **Vesting schedules on active vesting accounts are automatically migrated** during the hard fork so they continue unlocking on the same real-world cadence. No operator action is required. +- **The zkApp per-block command soft limit is lowered** from 24 to 12, ensuring SNARK workers can keep up with the faster 90-second block cadence. This change is delivered via soft fork before Mesa. +- **SNARK coordinators handling maximum-cost zkApp transactions should deploy at least 4 workers** (≈4 CPU cores each) to keep up with the new 90-second slot timing. A prerequisite SNARK-worker parallelization is delivered via soft fork before Mesa. -### Larger Events and Actions +### Expanded zkApp State — [MIP7](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0007-increase-state-size-limit.md) -Mesa raises the per-transaction limit on events and actions from 100 to 1024 field elements each, and removes the previous 16-field-element cap per individual event or action. Defined in [MIP8](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0008-increase-events-actions-limit.md). +Mesa raises the on-chain state available to a zkApp account from **8 field elements (indexes `0–7`) to 32 field elements (indexes `0–31`)**. zkApps can now store roughly four times more data directly on chain without off-chain workarounds. This applies to both the `zkapp_states` and `zkapp_states_nullable` database tables. See [Archive Node Schema Changes](/network-upgrades/mesa/appendix/archive-node-schema-changes) for the SQL diff. -### Larger zkApp Transactions +### Larger Events and Actions — [MIP8](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0008-increase-events-actions-limit.md) -Mesa roughly triples the maximum number of account updates a single zkApp transaction can contain. Defined in [MIP9](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0009-increase-zkapp-account-update-limit.md). +Mesa raises the per-transaction limit on events and actions from **100 field elements to 1024 field elements** for each. The previous cap of 16 field elements per individual event or action is also removed. This makes events and actions a viable channel for richer on-chain signaling and larger off-chain dispatch payloads in a single transaction. + +Mostly relevant to zkApp developers — node operators do not need to act on this change, but block producers will validate against the new limits automatically after the fork. + +### Larger zkApp Transactions — [MIP9](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0009-increase-zkapp-account-update-limit.md) + +Mesa **roughly triples** the maximum number of account updates a single zkApp transaction can contain. The previous weighted-cost formula (`10.26·np + 10.08·n2 + 9.14·n1 < 69.45`) is replaced with a simpler `np + n2 + n1 ≤ 16` rule that admits any balanced binary proof tree of height 4. + +This depends on the SNARK-worker parallelization shipped as a prerequisite for [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md) — without it, processing maximum-size transactions inside a 90-second slot would not be feasible. ### Mesa Package Naming Convention diff --git a/docs/network-upgrades/mesa/index.mdx b/docs/network-upgrades/mesa/index.mdx index 91e26df16..935010499 100644 --- a/docs/network-upgrades/mesa/index.mdx +++ b/docs/network-upgrades/mesa/index.mdx @@ -21,37 +21,16 @@ This documentation uses terms like _automode_, _stop-slot_, _trustless upgrade_, ## What Mesa Introduces -Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavior, plus two operational improvements to the upgrade flow itself. The canonical MIP specs live in the [MinaProtocol/MIPs](https://github.com/MinaProtocol/MIPs/tree/main/MIPS) repository; each section below links to the spec for the proposal it describes. +Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavior, plus two operational improvements to the upgrade flow itself. See the **[Glossary](/network-upgrades/mesa/glossary)** for detailed descriptions of each MIP and the canonical specs in the [MinaProtocol/MIPs](https://github.com/MinaProtocol/MIPs/tree/main/MIPS) repository. -### Faster Blocks — [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md) - -Mesa halves Mina's slot time from **180 seconds to 90 seconds**, doubling block production frequency. To keep the long-term token emission rate flat, the per-block **coinbase reward is also halved** (from 720 MINA to 360 MINA). The total Mina supplied per epoch is unchanged. - -Several second-order consequences flow from the slot-time change: - -- **Epoch duration halves** from ~14.9 days to ~7.4 days. Scripts and operational procedures tied to epoch boundaries (delegation cooldown, automated payouts, monitoring dashboards) trigger about twice as often. -- **Vesting schedules on active vesting accounts are automatically migrated** during the hard fork so they continue unlocking on the same real-world cadence. No operator action is required. -- **SNARK coordinators handling maximum-cost zkApp transactions should deploy at least 4 workers** (≈4 CPU cores each) to keep up with the new 90-second slot timing. A prerequisite SNARK-worker parallelization is delivered via soft fork before Mesa. - -### Expanded zkApp State — [MIP7](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0007-increase-state-size-limit.md) - -Mesa raises the on-chain state available to a zkApp account from **8 field elements (indexes `0–7`) to 32 field elements (indexes `0–31`)**. zkApps can now store roughly four times more data directly on chain without off-chain workarounds. - -### Larger Events and Actions — [MIP8](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0008-increase-events-actions-limit.md) - -Mesa raises the per-transaction limit on events and actions from **100 field elements to 1024 field elements** for each. The previous cap of 16 field elements per individual event or action is also removed. This makes events and actions a viable channel for richer on-chain signaling and larger off-chain dispatch payloads in a single transaction. - -Mostly relevant to zkApp developers — node operators do not need to act on this change, but block producers will validate against the new limits automatically after the fork. - -### Larger zkApp Transactions — [MIP9](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0009-increase-zkapp-account-update-limit.md) - -Mesa **roughly triples** the maximum number of account updates a single zkApp transaction can contain. The previous weighted-cost formula (`10.26·np + 10.08·n2 + 9.14·n1 < 69.45`) is replaced with a simpler `np + n2 + n1 ≤ 16` rule that admits any balanced binary proof tree of height 4. - -This depends on the SNARK-worker parallelization shipped as a prerequisite for [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md) — without it, processing maximum-size transactions inside a 90-second slot would not be feasible. +- **[Faster Blocks — MIP6](/network-upgrades/mesa/glossary#faster-blocks)** — Halves slot time to 90 seconds, halves coinbase reward, halves epoch duration. +- **[Expanded zkApp State — MIP7](/network-upgrades/mesa/glossary#expanded-zkapp-state)** — Raises on-chain state from 8 to 32 field elements per zkApp account. +- **[Larger Events and Actions — MIP8](/network-upgrades/mesa/glossary#larger-events-and-actions)** — Increases per-transaction event/action limit from 100 to 1024 field elements. +- **[Larger zkApp Transactions — MIP9](/network-upgrades/mesa/glossary#larger-zkapp-transactions)** — Triples the max account updates per zkApp transaction. ### Automode Upgrades -For the first time in Mina's history, block producers can upgrade through a hard fork **without manual intervention**. The automode mechanism ships both the pre-fork and post-fork binaries in a single package, with a dispatcher that automatically transitions to the new chain when the fork activates. Archive node and Rosetta API operators still use manual mode — automode is not available for those node types. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for details. +For the first time in Mina's history, block producers can upgrade through a hard fork **without manual intervention**. The automode mechanism ships both the pre-fork and post-fork binaries in a single package, with a dispatcher that automatically transitions to the new chain when the fork activates. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for details, including which node types do not support automode. ### Simplified Archive Upgrade @@ -79,78 +58,29 @@ The upgrade moves through four phases — **Pre-Upgrade**, **State Finalization* > **Goal:** Every participant is prepared and running the stop-slot release before the fork begins. -The table below is a high-level summary. The concrete install commands (Debian, Docker, etc.) and hardware requirements live in the [Requirements](/network-upgrades/mesa/requirements) and [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) pages — start there once you know your role and deployment style. - -| Actor | What to do | -|---|---| -| **All operators** | Verify [hardware requirements](/network-upgrades/mesa/requirements) (32 GB RAM, 8-core CPU with AVX/BMI2). Back up keys. | -| **Block Producers** | Choose [upgrade mode](/network-upgrades/mesa/upgrade-modes): **automode** (recommended) or manual. Install stop-slot release [3.x.x](https://github.com/MinaProtocol/mina/releases). If automode, install the `mina-{network}-automode` package — see [Installing automode](/network-upgrades/mesa/upgrade-modes#installing-automode). | -| **SNARK Coordinators** | A coordinator is a daemon node — follow the Block Producer path (automode or manual). | -| **Standalone SNARK Workers** | Workers spawned by a coordinator (`--run-snark-worker`) need no separate action — they inherit the coordinator's binary. Workers run as a separate `mina internal snark-worker` process or container must be redeployed with the Mesa release after the fork. | -| **Archive Nodes** | Install stop-slot release. Choose upgrade method: _trustless_ (run upgrade script now) or _trustful_ (import o1Labs dump later). If trustless, run the [archive upgrade script](/network-upgrades/mesa/archive-upgrade) — it is backward compatible and can be applied early. | -| **Exchanges** | Install stop-slot release. Update integrations (mina-signer, Rosetta API). Test on devnet. Plan deposit/withdrawal freeze window. | -| **zkApp Developers** | Update to the Mesa-compatible o1js version (`o1js@3.0.0-mesa.698ca` for the preflight chain), recompile your contract, and verify it on the [preflight network](/network-upgrades/mesa/preflight-network). Plan to redeploy on Mesa after the fork — every zkApp must be redeployed because the protocol version bump changes the verification key. {/* TODO(PR #1133): Link to the official o1js Mesa upgrade guide once published (cjjdespres #3220525842). */} | - -:::tip Readiness checklist -Review the [Requirements](/network-upgrades/mesa/requirements) and pick your [Upgrade Mode](/network-upgrades/mesa/upgrade-modes) before proceeding. -::: - ---- +Each actor type has a specific checklist — see **[Requirements](/network-upgrades/mesa/requirements)** for the full per-actor pre-upgrade procedures and hardware requirements. ### Phase 2: State Finalization — hours before the fork (exactly 5 hours) > **Goal:** The network reaches consensus on a final state. No new transactions are accepted. -At the predefined [**stop-transaction-slot**](/network-upgrades/mesa/fork-schedule), nodes stop accepting new user transactions. Block production continues for ~100 more slots with empty blocks (no coinbase, no fees) until the [**stop-network-slot**](/network-upgrades/mesa/fork-schedule) to ensure all nodes converge on the same state. The concrete slot numbers and timestamps live on the [Fork Schedule](/network-upgrades/mesa/fork-schedule) page. - -| Actor | What to do | -|---|---| -| **Block Producers** | **Keep your node running.** Block density during finalization is critical. Do not stop your node. | -| **SNARK Workers** | **Keep running.** Continue producing SNARK work. | -| **Archive Nodes** | Keep the archive node running to capture all finalized blocks. If doing trustless upgrade, run the upgrade script now if you haven't already. | -| **Exchanges** | **Disable MINA deposits and withdrawals.** Any transactions submitted after the stop-transaction-slot will not exist on the Mesa chain. | -| **zkApp Developers** | No action required. Monitor announcements. | - -:::danger For exchanges -Transactions submitted after the stop-transaction-slot **will not carry over** to the Mesa chain. Freeze all MINA activity before this point. -::: - ---- +At the predefined **stop-transaction-slot**, nodes stop accepting new user transactions. Block production continues for ~100 more slots with empty blocks until the **stop-network-slot**. See **[State Finalization](/network-upgrades/mesa/upgrade-steps/state-finalization)** for the full per-actor instructions. ### Phase 3: Upgrade — fork day (network is down) > **Goal:** The network halts, state is exported, and the Mesa release is published. -At the **stop-network-slot**, block production stops entirely. o1Labs exports the network state, builds the Mesa release with the final ledger baked in, and publishes packages and Docker images. - -| Actor | What to do | -|---|---| -| **Block Producers (automode)** | **Nothing.** Your node transitions to Mesa automatically. It will start producing blocks when the Mesa genesis timestamp arrives. | -| **Block Producers (manual)** | Stop your node. Wait for the Mesa release announcement. Install the new package. Restart with [updated flags](/network-upgrades/mesa/upgrade-steps/post-upgrade). | -| **SNARK Coordinators** | Same as block producers — automode transitions automatically, manual requires stop + install + restart. | -| **Standalone SNARK Workers** | Coordinator-spawned workers follow the coordinator automatically. Standalone workers (`mina internal snark-worker` process or container) must be stopped and redeployed with the Mesa binary; an older worker cannot submit work to a Mesa coordinator. | -| **Archive Nodes** | Install the Mesa archive node release. Point it at your upgraded database (trustless) or import the o1Labs SQL dump into a fresh database (trustful). | -| **Exchanges** | Install the Mesa release. Keep deposits/withdrawals disabled until Mesa block production begins. | - ---- +At the **stop-network-slot**, block production stops entirely. o1Labs exports the network state, builds the Mesa release, and publishes packages. See **[Fork Schedule](/network-upgrades/mesa/fork-schedule)** for the schedule values and **[Upgrade](/network-upgrades/mesa/upgrade-steps/upgrade)** for the per-actor instructions. ### Phase 4: Post-Upgrade — after the fork > **Goal:** Block production resumes on the Mesa network. Normal operations return. -Exactly **3 hours** after the _stop-network-slot_, at the predefined Mesa genesis timestamp, the first Mesa block is produced. - -| Actor | What to do | -|---|---| -| **Block Producers** | Verify your node is on the Mesa chain (`mina client status`). If automode, check that the `activated` file exists in your config directory (see [Troubleshooting](/network-upgrades/mesa/troubleshooting#how-do-i-know-which-binary-my-node-is-using)). Monitor block production. | -| **SNARK Workers** | Reconnect workers to the upgraded coordinator. Standalone workers must already be on the Mesa binary at this point. Verify SNARK work is being produced. | -| **Archive Nodes** | Verify the archive database is in sync. Run [validation checks](/network-upgrades/mesa/upgrade-steps/post-upgrade#in-depth-validation). Fix any missing blocks using archive tooling. | -| **Exchanges** | **Re-enable MINA deposits and withdrawals** once block production is confirmed and your systems are verified. | -| **zkApp Developers** | **Redeploy every zkApp** on Mesa — the protocol version bump invalidates Berkeley verification keys, so a redeploy is required before any zkApp can accept transactions. You can also take advantage of the expanded 32-field on-chain state at this point. | +Exactly **3 hours** after the _stop-network-slot_, at the predefined Mesa genesis timestamp, the first Mesa block is produced. See **[Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade)** for verification checklists. --- -For step-by-step instructions per phase, see [Upgrade Steps](/network-upgrades/mesa/upgrade-steps). For end-to-end walkthroughs by role (block producer, archive node, zkApp developer, exchange), see [Examples](/network-upgrades/mesa/upgrade-steps/examples). +For end-to-end walkthroughs by role (block producer, archive node, zkApp developer, exchange), see **[Examples](/network-upgrades/mesa/upgrade-steps/examples)**. ## Upgrade Modes @@ -158,18 +88,15 @@ The Mesa upgrade supports two modes for daemon node operators: **[Automode](/net See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for the full comparison, requirements, and the persistent-filesystem / process-restart constraints that automode imposes. For low-level details on the dispatcher and dual-binary architecture, see [Upgrade Modes — Details](/network-upgrades/mesa/appendix/upgrade-modes-details). -## Examples - -End-to-end walkthroughs of the four phases for different roles (block producer automode/manual, archive node, zkApp developer, exchange) live on the [Examples](/network-upgrades/mesa/upgrade-steps/examples) page. ## Quick Reference by Operator Type | Operator Type | Key Pages | |---|---| -| **Block Producers** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Modes](/network-upgrades/mesa/upgrade-modes), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade Flags](/network-upgrades/mesa/upgrade-steps/post-upgrade) | -| **SNARK Workers / Coordinators** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade Flags](/network-upgrades/mesa/upgrade-steps/post-upgrade) | -| **Archive Node Operators** | [Requirements](/network-upgrades/mesa/requirements), [Archive Upgrade](/network-upgrades/mesa/archive-upgrade), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) | -| **Rosetta API Operators** | [Requirements](/network-upgrades/mesa/requirements), [Archive Upgrade](/network-upgrades/mesa/archive-upgrade), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) | -| **Exchanges** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade), [Archive Node Schema Changes](/network-upgrades/mesa/appendix/archive-node-schema-changes) | +| **Block Producers** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Modes](/network-upgrades/mesa/upgrade-modes), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps) | +| **SNARK Workers / Coordinators** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps) | +| **Archive Node Operators** | [Requirements](/network-upgrades/mesa/requirements), [Archive Upgrade](/network-upgrades/mesa/archive-upgrade), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps) | +| **Rosetta API Operators** | [Requirements](/network-upgrades/mesa/requirements), [Archive Upgrade](/network-upgrades/mesa/archive-upgrade), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps) | +| **Exchanges** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Archive Node Schema Changes](/network-upgrades/mesa/appendix/archive-node-schema-changes) | ## Network Details diff --git a/docs/network-upgrades/mesa/preflight-network.mdx b/docs/network-upgrades/mesa/preflight-network.mdx index b900f7319..7d12e941a 100644 --- a/docs/network-upgrades/mesa/preflight-network.mdx +++ b/docs/network-upgrades/mesa/preflight-network.mdx @@ -1,19 +1,19 @@ --- -title: Connect to Mesa Preflight Network +title: Mesa Preflight Network sidebar_label: Preflight Network -description: Instructions for connecting to the Mesa upgrade preflight network for testing and validation. +description: Version reference and build matrix for the Mesa upgrade preflight testing network — Docker images, Debian packages, and compatible SDK releases. keywords: - Mesa upgrade - preflight network - testing network - - mesa daemon + - mesa version - docker - debian packages --- -# Connect to Mesa Preflight Network +# Mesa Preflight Network -The Mesa preflight network is a testing environment for validating the Mesa upgrade before deployment to devnet and mainnet. This network allows node operators and developers to test their infrastructure and applications with the new Mesa release. +The Mesa preflight network is a testing environment for validating the Mesa upgrade before deployment to devnet and mainnet. For step-by-step connection instructions, see [Preflight Setup](/network-upgrades/mesa/preflight-setup). :::tip Mesa preflight hard fork completed @@ -23,20 +23,10 @@ The transaction protocol bump is a breaking wire-format change: any node still r zkApp developers must rebuild and redeploy against **`o1js@3.0.0-mesa.698ca`** — the first o1js release that targets transaction protocol v5.0.0. Transactions produced by earlier o1js versions will be rejected by post-fork nodes. -A dedicated **Upgrade Steps** page covering the post-fork operator checklist will be linked from the Mesa Upgrade sidebar once it ships. - -::: - -:::caution Preflight Network Notice - -The preflight network is intended for testing purposes only. This network may experience instability, breaking changes, and unexpected behavior. Data on this network should not be considered persistent or reliable. - ::: ## Available Build Versions -The Mesa preflight network uses the following build versions: - **Current version (install this):** `4.0.0-preflight-3f038cb` — post-hard-fork release. Implements transaction protocol version **5.0.0** and is the only build compatible with the post-fork chain. **Compatible o1js release:** `o1js@3.0.0-mesa.698ca` — the matching SDK for transaction protocol v5.0.0. Install with `npm install o1js@3.0.0-mesa.698ca` (or the equivalent for your package manager) when developing or redeploying zkApps against the post-fork preflight network. @@ -46,7 +36,7 @@ The Mesa preflight network uses the following build versions: - `4.0.0-preflight-stop-2967b39` — stop-slot release used to carry nodes up to the fork. Pre-fork transaction protocol; incompatible with the post-fork chain. - `4.0.0-preflight1-b649c79` — original preflight build. Listed for reference only. -### Docker Images +## Docker Images Docker images are available for both `amd64` and `arm64` architectures, on the `bookworm` and `noble` base distributions: @@ -56,7 +46,7 @@ Docker images are available for both `amd64` and `arm64` architectures, on the ` For `noble`, swap `bookworm` for `noble` in the tag (e.g. `mina-daemon:4.0.0-preflight-3f038cb-noble-mesa`). -### Debian Packages +## Debian Packages Debian packages are available from the unstable repository: @@ -72,190 +62,6 @@ Available packages (each at version `4.0.0-preflight-3f038cb`): For detailed information about the Debian repository structure and configuration, please refer to the [Debian Repository documentation](https://unstable.apt.packages.minaprotocol.com/). -## Connecting to the Network - -To connect your node to the Mesa preflight network, you must use the preflight network seed peer list. - -### Required Parameter - -Add the following parameter to your mina daemon command: - -```bash ---peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt -``` - -### Example: Running with Docker - -To start a Mina daemon node using Docker: - -```bash -docker run --name mina-mesa-preflight -d \ - -p 8302:8302 \ - --restart=always \ - gcr.io/o1labs-192920/mina-daemon:4.0.0-preflight-3f038cb-bookworm-mesa \ - daemon \ - --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt -``` - -For production deployments, you'll want to mount configuration directories and add additional flags: - -```bash -docker run --name mina-mesa-preflight -d \ - -p 8302:8302 \ - --restart=always \ - -v $(pwd)/.mina-config:/root/.mina-config \ - gcr.io/o1labs-192920/mina-daemon:4.0.0-preflight-3f038cb-bookworm-mesa \ - daemon \ - --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt \ - --libp2p-keypair /data/.mina-config/keys/libp2p-key -``` - -### Example: Running with Debian Package - -First, install dependencies and configure the repository: - -```bash -# Step 1: Install dependencies -sudo apt-get install -y lsb-release ca-certificates wget gnupg - -# Step 2: Import the GPG key -wget -q https://unstable.apt.packages.minaprotocol.com/repo-signing-key.gpg \ - -O /etc/apt/trusted.gpg.d/minaprotocol.gpg - -# Step 3: Add the unstable repository with preflight channel -echo "deb https://unstable.apt.packages.minaprotocol.com $(lsb_release -cs) preflight" | \ - sudo tee /etc/apt/sources.list.d/mina-preflight.list - -# Step 4: Update and install -sudo apt-get update -sudo apt-get install -y mina-mesa=4.0.0-preflight-3f038cb -``` - -Then start the daemon: - -```bash -mina daemon \ - --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt \ - --libp2p-keypair ~/.mina-config/keys/libp2p-key -``` - -### Running Archive Node - -:::info Upgrading from Berkeley to Mesa - -If you have an existing Berkeley archive database that you want to upgrade to Mesa, please refer to the comprehensive [Archive Upgrade](archive-upgrade) guide for detailed instructions on: -- Upgrade prerequisites and requirements -- Running the upgrade script -- Rollback procedures -- Database schema changes -- Verification steps - -::: - -#### Installing and Running Mesa Archive Node - -An archive node stores the full history of the blockchain and provides a GraphQL API for querying historical data. It requires a PostgreSQL database. - -**Installation with Debian:** - -```bash -# Step 1: Install dependencies -sudo apt-get install -y lsb-release ca-certificates wget gnupg postgresql postgresql-contrib - -# Step 2: Import the GPG key -wget -q https://unstable.apt.packages.minaprotocol.com/repo-signing-key.gpg \ - -O /etc/apt/trusted.gpg.d/minaprotocol.gpg - -# Step 3: Add the repository -echo "deb https://unstable.apt.packages.minaprotocol.com $(lsb_release -cs) preflight" | \ - sudo tee /etc/apt/sources.list.d/mina-preflight.list - -# Step 4: Install mina-archive-mesa -sudo apt-get update -sudo apt-get install -y mina-archive-mesa=4.0.0-preflight-3f038cb - -# Step 5: Create PostgreSQL database -sudo -u postgres createdb archive -sudo -u postgres createuser archive_user -sudo -u postgres psql -c "ALTER USER archive_user WITH PASSWORD 'your-secure-password';" -sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE archive TO archive_user;" - -# Step 6: Start the archive node -mina-archive run \ - --postgres-uri postgresql://archive_user:your-secure-password@localhost:5432/archive \ - --server-port 3086 -``` - -**Using Docker:** - -```bash -# Start the archive node (assumes you have a PostgreSQL server running) -docker run --name mina-archive-mesa -d \ - -p 3086:3086 \ - --restart=always \ - gcr.io/o1labs-192920/mina-archive:4.0.0-preflight-3f038cb-bookworm-mesa \ - mina-archive run \ - --postgres-uri postgresql://archive_user:your-secure-password@postgres-host:5432/archive \ - --server-port 3086 -``` - -**Connecting Mina Daemon to Archive:** - -Configure your mina daemon to send blocks to the archive node: - -```bash -mina daemon \ - --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt \ - --archive-address localhost:3086 -``` - -### Installing and Running Rosetta - -Rosetta is a standardized API for blockchain integration. The Rosetta API requires both a mina daemon and an archive node. - -**Installation with Debian:** - -```bash -# Step 1: Install dependencies (if not already done) -sudo apt-get install -y lsb-release ca-certificates wget gnupg - -# Step 2: Import the GPG key (if not already done) -wget -q https://unstable.apt.packages.minaprotocol.com/repo-signing-key.gpg \ - -O /etc/apt/trusted.gpg.d/minaprotocol.gpg - -# Step 3: Add the repository (if not already done) -echo "deb https://unstable.apt.packages.minaprotocol.com $(lsb_release -cs) preflight" | \ - sudo tee /etc/apt/sources.list.d/mina-preflight.list - -# Step 4: Install mina-rosetta-mesa -sudo apt-get update -sudo apt-get install -y mina-rosetta-mesa=4.0.0-preflight-3f038cb - -# Step 5: Start Rosetta -# Rosetta connects to both the mina daemon and archive node -mina-rosetta \ - --port 3087 \ - --archive-uri http://localhost:3086/graphql \ - --graphql-uri http://localhost:3085/graphql -``` - -**Using Docker:** - -```bash -docker run --name mina-rosetta-mesa -d \ - -p 3087:3087 \ - --restart=always \ - gcr.io/o1labs-192920/mina-rosetta:4.0.0-preflight-3f038cb-bookworm-mesa \ - --port 3087 \ - --archive-uri http://archive-host:3086/graphql \ - --graphql-uri http://mina-daemon-host:3085/graphql -``` - -**Note:** Rosetta requires: -- A running mina daemon (GraphQL endpoint, typically port 3085) -- A running archive node (GraphQL endpoint, typically port 3086) -- Both must be fully synced for Rosetta to function properly - ## Nightly Builds In addition to the preflight release builds, nightly builds are also available for testing the latest changes. @@ -266,40 +72,7 @@ Nightly builds are available for both Debian packages and Docker images. These b For more information about nightly builds and repository configuration, see the [Debian Repository documentation](https://nightly.apt.packages.minaprotocol.com/). -## Verification - -After starting your node, verify connectivity to the preflight network: - -### Check Node Status - -```bash -# For Docker -docker exec -it mina-mesa-preflight mina client status - -# For Debian installation -mina client status -``` - -### Monitor Logs - -```bash -# For Docker -docker logs -f mina-mesa-preflight - -# For systemd service (Debian) -journalctl -u mina -f -``` - -## Support and Feedback - -If you encounter issues or have feedback about the Mesa preflight network: - -1. Check the [Mina Protocol Discord](https://discord.gg/minaprotocol) for community support -2. Report issues on the [Mina GitHub repository](https://github.com/MinaProtocol/mina/issues) -3. Join the Mesa upgrade discussions in the community channels - ## Next Steps -- Explore additional Mesa upgrade documentation -- Test your applications and infrastructure against the preflight network -- Provide feedback to help improve the Mesa upgrade process +- [Connect to the Preflight Network](/network-upgrades/mesa/preflight-setup) — Docker and Debian setup guides +- [Mesa Upgrade Overview](/network-upgrades/mesa) — prepare for mainnet diff --git a/docs/network-upgrades/mesa/preflight-setup.mdx b/docs/network-upgrades/mesa/preflight-setup.mdx new file mode 100644 index 000000000..9d571e2d2 --- /dev/null +++ b/docs/network-upgrades/mesa/preflight-setup.mdx @@ -0,0 +1,202 @@ +--- +title: Connect to Mesa Preflight Network +sidebar_label: Preflight Setup +description: Step-by-step instructions for connecting daemon, archive, and Rosetta nodes to the Mesa preflight testing network. +keywords: + - Mesa upgrade + - preflight network + - testing network + - mesa daemon + - docker + - debian packages +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Connect to Mesa Preflight Network + +The Mesa preflight network is a testing environment for validating the Mesa upgrade before deployment to devnet and mainnet. This page walks through connecting each node type. + +Before starting, check the [Preflight Network](/network-upgrades/mesa/preflight-network) page for the current build versions, Docker image tags, and Debian package names. + +:::caution Preflight Network Notice + +The preflight network is intended for testing purposes only. This network may experience instability, breaking changes, and unexpected behavior. Data on this network should not be considered persistent or reliable. + +::: + +## Connecting to the Network + +All node types must use the preflight network seed peer list: + +```bash +--peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt +``` + + + + +### Mina Daemon + +```bash +docker run --name mina-mesa-preflight -d \ + -p 8302:8302 \ + --restart=always \ + gcr.io/o1labs-192920/mina-daemon:4.0.0-preflight-3f038cb-bookworm-mesa \ + daemon \ + --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt +``` + +For production deployments, mount config directories and add additional flags: + +```bash +docker run --name mina-mesa-preflight -d \ + -p 8302:8302 \ + --restart=always \ + -v $(pwd)/.mina-config:/root/.mina-config \ + gcr.io/o1labs-192920/mina-daemon:4.0.0-preflight-3f038cb-bookworm-mesa \ + daemon \ + --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt \ + --libp2p-keypair /data/.mina-config/keys/libp2p-key +``` + +### Archive Node + +```bash +docker run --name mina-archive-mesa -d \ + -p 3086:3086 \ + --restart=always \ + gcr.io/o1labs-192920/mina-archive:4.0.0-preflight-3f038cb-bookworm-mesa \ + mina-archive run \ + --postgres-uri postgresql://archive_user:your-secure-password@postgres-host:5432/archive \ + --server-port 3086 +``` + +If upgrading an existing Berkeley database, see [Archive Upgrade](/network-upgrades/mesa/archive-upgrade). + +### Rosetta API + +```bash +docker run --name mina-rosetta-mesa -d \ + -p 3087:3087 \ + --restart=always \ + gcr.io/o1labs-192920/mina-rosetta:4.0.0-preflight-3f038cb-bookworm-mesa \ + --port 3087 \ + --archive-uri http://archive-host:3086/graphql \ + --graphql-uri http://mina-daemon-host:3085/graphql +``` + +**Note:** Rosetta requires a running Mina daemon (port 3085) and archive node (port 3086). Both must be fully synced. + + + + +First, install dependencies and configure the repository: + +```bash +# Step 1: Install dependencies +sudo apt-get install -y lsb-release ca-certificates wget gnupg + +# Step 2: Import the GPG key +wget -q https://unstable.apt.packages.minaprotocol.com/repo-signing-key.gpg \ + -O /etc/apt/trusted.gpg.d/minaprotocol.gpg + +# Step 3: Add the unstable repository with preflight channel +echo "deb https://unstable.apt.packages.minaprotocol.com $(lsb_release -cs) preflight" | \ + sudo tee /etc/apt/sources.list.d/mina-preflight.list + +# Step 4: Update and install +sudo apt-get update +sudo apt-get install -y mina-mesa=4.0.0-preflight-3f038cb +``` + +### Mina Daemon + +```bash +mina daemon \ + --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt \ + --libp2p-keypair ~/.mina-config/keys/libp2p-key +``` + +### Archive Node + +```bash +# Install archive package +sudo apt-get install -y mina-archive-mesa=4.0.0-preflight-3f038cb + +# Create PostgreSQL database (if needed) +sudo -u postgres createdb archive +sudo -u postgres createuser archive_user +sudo -u postgres psql -c "ALTER USER archive_user WITH PASSWORD 'your-secure-password';" +sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE archive TO archive_user;" + +# Start archive node +mina-archive run \ + --postgres-uri postgresql://archive_user:your-secure-password@localhost:5432/archive \ + --server-port 3086 +``` + +If upgrading an existing Berkeley database, see [Archive Upgrade](/network-upgrades/mesa/archive-upgrade). + +### Rosetta API + +```bash +sudo apt-get install -y mina-rosetta-mesa=4.0.0-preflight-3f038cb + +mina-rosetta \ + --port 3087 \ + --archive-uri http://localhost:3086/graphql \ + --graphql-uri http://localhost:3085/graphql +``` + + + + +### Connecting Mina Daemon to Archive + +Configure your daemon to send blocks to the archive node: + +```bash +mina daemon \ + --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt \ + --archive-address localhost:3086 +``` + +## Verification + +After starting your node, verify connectivity to the preflight network: + +### Check Node Status + +```bash +# For Docker +docker exec -it mina-mesa-preflight mina client status + +# For Debian installation +mina client status +``` + +### Monitor Logs + +```bash +# For Docker +docker logs -f mina-mesa-preflight + +# For systemd service (Debian) +journalctl -u mina -f +``` + +## Support and Feedback + +If you encounter issues or have feedback about the Mesa preflight network: + +1. Check the [Mina Protocol Discord](https://discord.gg/minaprotocol) for community support +2. Report issues on the [Mina GitHub repository](https://github.com/MinaProtocol/mina/issues) +3. Join the Mesa upgrade discussions in the community channels + +## Next Steps + +- Test your applications and infrastructure against the preflight network +- Review the [Mesa Upgrade](/network-upgrades/mesa) overview for mainnet preparation +- Provide feedback to help improve the Mesa upgrade process diff --git a/docs/network-upgrades/mesa/requirements.mdx b/docs/network-upgrades/mesa/requirements.mdx index e83a6a79e..48d9aa4d6 100644 --- a/docs/network-upgrades/mesa/requirements.mdx +++ b/docs/network-upgrades/mesa/requirements.mdx @@ -2,11 +2,12 @@ title: Requirements sidebar_label: Requirements hide_title: true -description: Hardware and connectivity requirements for daemon node operators upgrading to Mesa — block producers, SNARK coordinators, archive nodes, Rosetta API nodes, and seed nodes. +description: Hardware requirements and pre-upgrade checklist for all node operator types upgrading to Mesa — block producers, SNARK coordinators, archive nodes, Rosetta API, and exchanges. keywords: - Mesa - upgrade - hardware requirements + - pre-upgrade --- # Requirements @@ -47,3 +48,46 @@ mina libp2p generate-keypair --privkey-path ``` Further information on [generating a libp2p key pair](/node-operators/seed-peers/generating-a-libp2p-keypair) on Mina Protocol. + +## Pre-Upgrade Checklist + +Before the fork, each actor type must complete specific preparations. Complete these steps **weeks before the fork** to ensure a smooth upgrade. + +### All operators + +- Verify your hardware meets the [requirements](#hardware-requirements) above (32 GB RAM, 8-core CPU with AVX/BMI2). +- Back up your keys and configuration before installing any new packages. + +### Block Producers + +- Choose your [Upgrade Mode](/network-upgrades/mesa/upgrade-modes): **automode** (recommended) or manual. +- Install the stop-slot release [3.x.x](https://github.com/MinaProtocol/mina/releases). +- If using automode, install the `mina-{network}-automode` package. See [Installing automode](/network-upgrades/mesa/upgrade-modes#installing-automode). + +### SNARK Coordinators + +- A coordinator is a daemon node — follow the Block Producer path above (automode or manual). + +### Standalone SNARK Workers + +- Workers spawned by a coordinator (`--run-snark-worker`) need no separate action — they inherit the coordinator's binary. +- Workers run as a separate `mina internal snark-worker` process or container must be redeployed with the Mesa release after the fork. + +### Archive Nodes + +- Install the stop-slot release. +- Choose your upgrade method: [_trustless_](/network-upgrades/mesa/glossary#trustless) (run the upgrade script now) or [_trustful_](/network-upgrades/mesa/glossary#trustful) (import o1Labs dump later). +- If doing trustless, run the [Archive Upgrade](/network-upgrades/mesa/archive-upgrade) script — it can be applied before the fork while the Berkeley archive node is still running. + +### Exchanges + +- Install the stop-slot release. +- Update integrations (mina-signer, Rosetta API). +- Test on devnet. +- Plan your deposit/withdrawal freeze window around the [`stop-transaction-slot`](/network-upgrades/mesa/glossary#stop-transaction-slot). + +### zkApp Developers + +- Update to the Mesa-compatible o1js version (`o1js@3.0.0-mesa.698ca` for the preflight chain). +- Recompile your contracts and verify them on the [preflight network](/network-upgrades/mesa/preflight-network). +- Plan to redeploy every zkApp on Mesa — each must be redeployed because the protocol version bump changes the verification key. {/* TODO(PR #1133): Link to the official o1js Mesa upgrade guide once published (cjjdespres #3220525842). */} diff --git a/docs/network-upgrades/mesa/upgrade-steps/examples.mdx b/docs/network-upgrades/mesa/upgrade-steps/examples.mdx index 6b54d1b1d..578db0c53 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/examples.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/examples.mdx @@ -52,12 +52,12 @@ mina client status ``` :::note Dispatcher and non-daemon commands -The automode dispatcher only supports the `daemon` subcommand and `client status` command — it cannot determine the active runtime for other commands because they don't pass the config directory. For commands like `accounts list`, or `ledger export`, use the correct version-specific binary directly: `mina-mesa` (after the fork) or `mina-berkeley` (before the fork). The full paths `/usr/lib/mina/mesa/mina` and `/usr/lib/mina/berkeley/mina` also work. This limitation may be removed in a future release. +The automode dispatcher only supports `daemon` and `client status` subcommands. For other commands, use `mina-mesa` or `mina-berkeley` directly. See [Troubleshooting](/network-upgrades/mesa/troubleshooting#can-i-run-non-daemon-commands-or-use-a-specific-binary-version) for details. ::: She's done. Her node is producing blocks on Mesa. -> For post-upgrade flags and monitoring, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade). +> For post-upgrade verification, monitoring, and flag reference, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference). @@ -120,7 +120,7 @@ docker run --name mina -d \ docker exec mina mina client status # confirms Mesa chain ID ``` -> For post-upgrade flags and monitoring, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade). +> For post-upgrade verification, monitoring, and flag reference, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference). @@ -270,7 +270,7 @@ sudo apt-get install mina-mainnet=3.x.x **Hours before the fork** — Before the _stop-transaction-slot_ arrives, Bob **disables MINA deposits and withdrawals** on his platform and notifies customers about the maintenance window. :::danger -Any transactions submitted after the stop-transaction-slot **will not exist on the Mesa chain**. This is the most critical step for exchanges. +Any transactions submitted after the stop-transaction-slot **will not exist on the Mesa chain**. See [State Finalization](/network-upgrades/mesa/upgrade-steps/state-finalization#exchanges) for the full exchange guidance. ::: **Fork day** — The network halts. Bob waits for the Mesa release announcement, then upgrades: @@ -291,6 +291,6 @@ mina client status # verify Mesa chain ID # test a small internal transfer before opening to customers ``` -> For post-upgrade flags and configurations, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade). +> For post-upgrade verification, monitoring, and flag reference, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference). diff --git a/docs/network-upgrades/mesa/upgrade-steps/index.mdx b/docs/network-upgrades/mesa/upgrade-steps/index.mdx index 33ac23b6f..3f7f33fcb 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/index.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/index.mdx @@ -23,7 +23,7 @@ The Mesa upgrade proceeds through four sequential phases. Each phase has specifi | [Pre-Upgrade](/network-upgrades/mesa/requirements) | Prepare infrastructure, upgrade to the stop-slot release, run archive upgrade scripts | | [State Finalization](/network-upgrades/mesa/upgrade-steps/state-finalization) | 100-slot stabilization period — no new transactions accepted, block production continues | | [Upgrade](/network-upgrades/mesa/upgrade-steps/upgrade) | Network halts, state is exported, Mesa build is published | -| [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) | Block production resumes on Mesa, flags and configurations for the new network | +| [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) | Block production resumes on Mesa — verification and health checks for the new network | **Please note:** A simplified Node Status service will be part of the upgrade tooling and enabled by default in the Pre-Upgrade release with stop-slots ([3.x.x](https://github.com/MinaProtocol/mina/releases)). This feature allows for a safe upgrade by monitoring the amount of upgraded active stake. Only non-sensitive data is reported. @@ -37,7 +37,7 @@ Role-specific quick references: - **Block Producers & SNARK Coordinators** — pick a mode on [Upgrade Modes](/network-upgrades/mesa/upgrade-modes). Install commands for automode are in [Upgrade Modes — Installing automode](/network-upgrades/mesa/upgrade-modes#installing-automode). - **SNARK Workers** — coordinator-spawned workers inherit the coordinator's binary; standalone `mina internal snark-worker` deployments must be redeployed with the Mesa binary after the fork. -- **Archive Node Operators** — archive nodes do **not** support automode. See [Archive Upgrade](/network-upgrades/mesa/archive-upgrade) for the schema upgrade and trustless/trustful paths. +- **Archive Node Operators** — Archive nodes do **not** support automode (see [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for limitations). See [Archive Upgrade](/network-upgrades/mesa/archive-upgrade) for the schema upgrade and trustless/trustful paths. - **Exchanges** — disable MINA deposits and withdrawals before the _stop-transaction-slot_ and keep them disabled until Mesa block production resumes. See [Exchanges](/network-upgrades/mesa/upgrade-steps/post-upgrade) on the Post-Upgrade page for the re-enable checklist. :::danger For exchanges diff --git a/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx b/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx index 8dfa2e37a..c0b3a8595 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx @@ -21,6 +21,17 @@ Exactly 3 hours after the network reaches the _stop-network-slot_, at the predef This page helps you **verify your node is healthy** and running on the Mesa chain. +## Per-actor summary + +| Actor | During this phase | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Block Producers** | Verify your node is on the Mesa chain (`mina client status`). If using automode, check the `activated` file. Monitor block production. | +| **SNARK Workers** | Reconnect workers to the upgraded coordinator. Standalone workers must already be on the Mesa binary. Verify SNARK work is being produced. | +| **Archive Node Operators** | Verify the archive database is in sync. Run [validation checks](#in-depth-validation). Fix any missing blocks. | +| **Rosetta Operators** | Complete the archive node checks first, then verify Rosetta is responding. Run `rosetta-cli` validation. | +| **Exchanges** | **Re-enable MINA deposits and withdrawals** once block production is confirmed and your systems are verified end to end. | +| **zkApp Developers** | **Redeploy every zkApp** on Mesa — the protocol version bump invalidates Berkeley verification keys. Verify your contracts against o1js v3 / protocol v5. Use the expanded 32-field on-chain state. | + The checks are split into separate tabs for **Rosetta API** and **Exchange** because the two roles overlap but are not the same. _Rosetta API_ here means an operator running the `mina-rosetta` integration layer (typically alongside an archive node). _Exchange_ means an operator running the customer-facing platform that ingests Mina balances and submits payments. Most exchanges use Rosetta, so they will work through both tabs; a handful operate without Rosetta (custom GraphQL integrations) and can skip the Rosetta tab. ## Verify Your Node @@ -36,6 +47,7 @@ mina client status ``` You should see: + - **Sync status**: `Synced` - **Chain ID** matching the Mesa chain ID for your network. The chain ID changes at the fork and is network-specific (mainnet, devnet, and preflight each get their own) — the exact value is published in the Mesa release announcement alongside the first Mesa packages. - **Git SHA-1** matching the published Mesa daemon commit @@ -119,6 +131,8 @@ Rosetta depends on a healthy archive database. #### 2. Verify Rosetta is responding +For the full Rosetta API setup and verification guide, see [Rosetta API](/node-operators/data-and-history/rosetta). + ```bash curl -s http://localhost:3088/network/list \ -H 'Content-Type: application/json' \ @@ -150,6 +164,7 @@ curl -s http://localhost:3088/account/balance \ #### 2. Re-enable deposits and withdrawals Only re-enable MINA deposits and withdrawals after: + - Block production is confirmed (blocks are advancing) - Your integration is verified end to end - You have confirmed balances match expectations @@ -165,11 +180,13 @@ The checks in the tabs above cover basic health. This section provides deeper va 1. **Verify signature kind** — query the GraphQL endpoint to confirm the correct signature kind: + ```graphql query { signatureKind } ``` + For mainnet, this should return `mainnet`. 2. **Verify connectivity** — ensure your node has peers and is connected to the network. Check that the node is receiving and gossiping blocks. @@ -180,6 +197,7 @@ The checks in the tabs above cover basic health. This section provides deeper va Use the `mina-archive-hardfork-toolbox` to verify the upgrade. All commands require `--postgres-uri postgresql://:@:/`. See the [Archive Upgrade](/network-upgrades/mesa/archive-upgrade#verification-with-the-archive-hardfork-toolbox) page for full toolbox documentation. **Verify schema upgrade:** + ```bash mina-archive-hardfork-toolbox verify-upgrade \ --postgres-uri \ @@ -188,11 +206,13 @@ mina-archive-hardfork-toolbox verify-upgrade \ ``` You can also verify manually: + ```sql SELECT * FROM migration_history; ``` **Validate fork block integrity** (after the fork activates): + ```bash mina-archive-hardfork-toolbox validate-fork \ --postgres-uri \ @@ -201,6 +221,7 @@ mina-archive-hardfork-toolbox validate-fork \ ``` **Verify no commands after fork point:** + ```bash mina-archive-hardfork-toolbox fork-candidate no-commands-after \ --postgres-uri \ @@ -209,20 +230,24 @@ mina-archive-hardfork-toolbox fork-candidate no-commands-after \ ``` **Verify extended zkApp state columns exist:** + ```sql SELECT column_name FROM information_schema.columns WHERE table_name = 'zkapp_states_nullable' AND column_name LIKE 'element%' ORDER BY column_name; ``` + Confirm columns `element0` through `element31` exist. **Check for missing blocks:** + ```bash mina-missing-blocks-auditor --archive-uri postgres://:@
:/ ``` **Compare block heights** — the archive height should match or be close to the daemon's reported height: + ```sql SELECT MAX(height) FROM blocks; ``` @@ -288,25 +313,17 @@ The Node Status reporting service is **enabled by default** on the Mesa daemon. To opt out of the Node Status service entirely, pass `--disable-node-status` (no value). Note: the previously-documented `--node-stats-type full|none` argument was never accepted by the daemon — `--simplified-node-stats` and `--disable-node-status` are the actual flag names in the Mesa release. -## Report Issues - -If you encounter any problems after the upgrade: - -- Report bugs on [GitHub](https://github.com/MinaProtocol/mina/issues) with the label `mesa` -- Reach out on [Discord](https://discord.gg/minaprotocol) in the appropriate channel - ---- - ## Flag and Configuration Reference The flags below are **unchanged from Berkeley** — if your node was running correctly before the fork, the same flags will work on Mesa. This section is provided as a reference for operators setting up fresh nodes or verifying their configuration. -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`). */} +For the canonical flag reference, see the [Validator Node docs](/node-operators/validator-node/connecting-to-the-network), [Block Producer docs](/node-operators/block-producer-node/getting-started), [SNARK Worker docs](/node-operators/snark-workers/getting-started), and [Archive Node docs](/node-operators/archive-node). :::info What changed in Mesa + - **Only if you manually manage your genesis config or genesis ledgers, repoint `--genesis-ledger-dir` and `-config-file` at the Mesa-specific files.** Operators who rely on the package-installed genesis config — including all automode users — do not need to change anything. If you do override them, 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`). - **All other flags carry over unchanged** — `--block-producer-key`, `--libp2p-keypair`, `--peer-list-url`, `--external-ip/port`, log flags, etc. behave the same on Mesa as on Berkeley. -::: + :::
Block Producer flags @@ -331,6 +348,8 @@ ENVIRONMENT VARIABLES
SNARK Coordinator flags +For detailed flag descriptions, see [SNARK Workers — Getting Started](/node-operators/snark-workers/getting-started). + ``` mina daemon --config-directory @@ -352,6 +371,8 @@ ENVIRONMENT VARIABLES
SNARK Worker flags +For detailed flag descriptions, see [SNARK Workers — Getting Started](/node-operators/snark-workers/getting-started). + ``` mina internal snark-worker --proof-level full @@ -418,3 +439,10 @@ docker run \ ```
+ +## Report Issues + +If you encounter any problems after the upgrade: + +- Report bugs on [GitHub](https://github.com/MinaProtocol/mina/issues) with the label `mesa` +- Reach out on [Discord](https://discord.gg/minaprotocol) in the appropriate channel diff --git a/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx b/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx index 4efd5d1b1..7a91e0b5b 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx @@ -19,6 +19,17 @@ During the state finalization slots, it is crucial to maintain a high block dens Archive nodes should also continue to execute to ensure finalized blocks are in the database and can be carried over to the upgraded schema, preserving the integrity and accessibility of the network's history. +## Per-actor summary + +| Actor | During this phase | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Block Producers** | Keep your node running. Block density during finalization is critical — do not stop your node. Both automode and manual operators simply keep running. | +| **SNARK Workers** | Continue producing SNARK work. No special action required. | +| **Archive Node Operators** | Keep the archive node running to capture all finalized blocks. If doing trustless upgrade, run the [archive upgrade script](/network-upgrades/mesa/archive-upgrade) now if not done already. | +| **Rosetta Operators** | Follow the archive node instructions — keep your archive node running. | +| **Exchanges** | **Disable MINA deposits and withdrawals.** Any transactions submitted after the stop-transaction-slot will not carry over to the Mesa chain. | +| **zkApp Developers** | No action required. Monitor announcements for the Mesa genesis timestamp. | + ## 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. @@ -36,7 +47,7 @@ During this phase, both Automode and Manual mode operators simply keep their nod If you are doing the trustless upgrade, 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. +2. Execute the [archive node upgrade script](/network-upgrades/mesa/archive-upgrade). It can be applied before the fork. 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](/network-upgrades/mesa/archive-upgrade) section. diff --git a/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx index b1c395208..cb6881052 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx @@ -16,6 +16,18 @@ Starting at the _stop-network-slot_ the network will not produce nor accept new There is a tool available to validate that the Mesa node was built from the pre-upgrade network state. See [In-Depth Validation](/network-upgrades/mesa/upgrade-steps/post-upgrade#in-depth-validation) for the `mina-archive-hardfork-toolbox` commands (`validate-fork`, `fork-candidate no-commands-after`) used to verify fork-block integrity. {/* TODO(PR #1133): If/when an authoritative `upgrading-to-mesa.md` lands in MinaProtocol/mina, link to it here. The previous link to `mina/blob/mesa/docs/upgrading-to-mesa.md` returned 404 — the `mesa` branch does not exist on the main repo. */} +## Per-actor summary + +| Actor | During this phase | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Block Producers (automode)** | Nothing. Your node transitions to Mesa automatically and will start producing blocks at the Mesa genesis timestamp. | +| **Block Producers (manual)** | Stop your node. Wait for the Mesa release announcement, then install the new package and restart with [updated flags](/network-upgrades/mesa/upgrade-steps/post-upgrade). | +| **SNARK Coordinators** | Same as block producers — automode transitions automatically; manual requires stop, install, and restart. | +| **Standalone SNARK Workers** | Stop old workers. After the Mesa release is published, redeploy and start workers against the Mesa coordinator — an older worker cannot submit work to a Mesa coordinator. | +| **Archive Node Operators** | Install the Mesa archive node release. Point it at your upgraded database (trustless) or import the o1Labs SQL dump (trustful). | +| **Rosetta Operators** | Follow the archive node upgrade procedure for your archive database. Install the Mesa Rosetta release when published. | +| **Exchanges** | Install the Mesa release if running node infrastructure. **Keep deposits/withdrawals disabled** until block production is confirmed on the Mesa chain (see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade)). | + ## Block Producers and SNARK Workers :::info @@ -25,8 +37,8 @@ If you are using [Automode](/network-upgrades/mesa/upgrade-modes), your node han If you are using **Manual mode**: 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. Pass it to the Mesa daemon with the [`--libp2p-keypair`](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference) flag (see the Flag and Configuration Reference on the Post-Upgrade page). +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 Mesa genesis timestamp, which is when the first Mesa block will be produced. +3. It is possible to continue using the same libp2p key after the upgrade. Pass it to the Mesa daemon with the [`--libp2p-keypair`](/node-operators/block-producer-node/getting-started) flag. All daemon flags carry over unchanged from Berkeley — see the [Post-Upgrade flag reference](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference) for the full per-role configuration. ## Archive Node Operators and Rosetta Operators diff --git a/docusaurus.config.js b/docusaurus.config.js index efd128337..03736aa51 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -340,6 +340,10 @@ module.exports = { from: '/mesa-upgrade/archive-upgrade', to: '/network-upgrades/mesa/archive-upgrade', }, + { + from: '/mesa-upgrade/fork-schedule', + to: '/network-upgrades/mesa/fork-schedule', + }, { from: '/mesa-upgrade/flags-configs', to: '/network-upgrades/mesa/upgrade-steps/post-upgrade', @@ -352,6 +356,7 @@ module.exports = { from: '/network-upgrades/mesa/appendix', to: '/network-upgrades/mesa/appendix/archive-node-schema-changes', }, + // Redirect removed — /network-upgrades/mesa/fork-schedule now resolves to the restored standalone page. { from: '/network-upgrades/mesa/upgrade-modes-details', to: '/network-upgrades/mesa/appendix/upgrade-modes-details', diff --git a/sidebars.js b/sidebars.js index 16f904157..c431c6f8b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -73,6 +73,7 @@ module.exports = { }, 'network-upgrades/mesa/archive-upgrade', 'network-upgrades/mesa/preflight-network', + 'network-upgrades/mesa/preflight-setup', 'network-upgrades/mesa/troubleshooting', { type: 'category', diff --git a/src/theme/Admonition/index.tsx b/src/theme/Admonition/index.tsx index a36cd0b55..861837089 100644 --- a/src/theme/Admonition/index.tsx +++ b/src/theme/Admonition/index.tsx @@ -238,7 +238,7 @@ export default function Admonition(props: Props): JSX.Element { admonitionStyles = styles.admonitionTip; } else if (type === 'info') { admonitionStyles = styles.admonitionInfo; - } else if (type === 'danger' || type === 'caution') { + } else if (type === 'danger' || type === 'caution' || type === 'warning') { admonitionStyles = styles.admonitionDanger; } else if (type === 'experimental') { admonitionStyles = styles.admonitionExperimental; diff --git a/static/llms-full.txt b/static/llms-full.txt index d78597c9d..457856def 100644 --- a/static/llms-full.txt +++ b/static/llms-full.txt @@ -3876,15 +3876,9 @@ url: /network-upgrades Mina Protocol evolves through network upgrades (hard forks). Each upgrade introduces new protocol features, performance improvements, or governance changes. Hard forks are not backward compatible — all node operators must upgrade before the fork activates. -:::tip Mesa preflight hard fork completed - -The Mesa preflight network hard-forked at **2026-04-27 13:00 UTC**. The post-fork chain is now running the Mesa release **`4.0.0-preflight-3f038cb`**, which raises the **transaction protocol version to 5.0.0**. - -Operators must run **`4.0.0-preflight-3f038cb`** to remain on the preflight network. Earlier builds — including the stop-slot release `4.0.0-preflight-stop-2967b39` — are no longer compatible with the post-fork chain. +:::tip Mesa preflight update -zkApp developers must update to **`o1js@3.0.0-mesa.698ca`**, which targets transaction protocol v5.0.0; earlier o1js releases will produce transactions that the post-fork network rejects. - -See [Preflight Network](/network-upgrades/mesa/preflight-network) for the full upgrade path. +The Mesa preflight network hard fork completed on **2026-04-27 13:00 UTC**. See [Preflight Network](/network-upgrades/mesa/preflight-network) for the current build versions and upgrade path. ::: @@ -4224,22 +4218,44 @@ url: /network-upgrades/mesa/archive-upgrade This guide describes the general procedure for upgrading a Mina archive database from Berkeley to Mesa. The same steps apply to every Mesa deployment (preflight, devnet, mainnet) — only the archive package version differs. -:::tip Mesa preflight hard fork completed +:::tip Preflight-specific version info -The Mesa preflight network hard-forked at **2026-04-27 13:00 UTC**. The post-fork chain runs **`4.0.0-preflight-3f038cb`**, which raises the **transaction protocol version to 5.0.0**. Pre-fork builds — including the stop-slot release `4.0.0-preflight-stop-2967b39` — are no longer compatible. - -When upgrading a preflight archive database, install the matching `mina-archive-mesa=4.0.0-preflight-3f038cb` package so the archive node speaks the new transaction protocol. +The Mesa preflight network has already forked. See [Preflight Network](/network-upgrades/mesa/preflight-network) for the current build versions and transaction protocol details. ::: -:::info Choosing the Mesa archive version + + + +The preflight archive version is **`4.0.0-preflight-3f038cb`** (post-hard-fork; transaction protocol v5.0.0). Docker tag: `gcr.io/o1labs-192920/mina-archive:4.0.0-preflight-3f038cb-bookworm-mesa`. See [Preflight Network](./preflight-network) for the full release matrix. + +```bash +# Substitute this version wherever appears below +MESA_VERSION=4.0.0-preflight-3f038cb +``` -The commands below use `` as a placeholder for the archive build you want to install. Substitute the tag that matches your target network: + + -- **Preflight network** — use `4.0.0-preflight-3f038cb` (post-hard-fork; transaction protocol v5.0.0). See [Preflight Network](./preflight-network) for the full release matrix. -- **Devnet / mainnet** — use the Mesa release tag published for that network when it is announced. +The devnet Mesa archive version will be published when the devnet fork is scheduled. Check [Mina releases](https://github.com/MinaProtocol/mina/releases?q=mesa) for the latest tag. -::: +```bash +# Substitute this version wherever appears below +MESA_VERSION= +``` + + + + +The mainnet Mesa archive version will be published in the Mesa release announcement. Check [Mina releases](https://github.com/MinaProtocol/mina/releases?q=mesa) for the `4.x.x` tag. + +```bash +# Substitute this version wherever appears below +MESA_VERSION= +``` + + + To successfully upgrade the archive database to Mesa, you must ensure that your environment meets the foundational requirements. @@ -4252,7 +4268,7 @@ To successfully upgrade the archive database to Mesa, you must ensure that your ## Archive database -One of the most obvious prerequisites is a Mainnet database. If you don't have an existing database with Devnet/Mainnet archive data, +One of the most obvious prerequisites is an archive database with Berkeley-era data. If you don't have an existing database with Devnet or Mainnet archive data, you can always download it from the O1Labs Google Cloud bucket. ## Upgrade process @@ -4464,14 +4480,14 @@ The relevant moments are: The mainnet Mesa fork schedule has not been announced. The values below are placeholders. They will be filled in once o1Labs publishes the stop-slot release and the Mesa genesis timestamp. ::: -| Field | Value | -|---|---| -| Pre-fork (stop-slot) release | _TBD — will be a `3.x.x` tag_ | -| Mesa release | _TBD — will be a `4.x.x` tag_ | -| `stop-transaction-slot` (`slot_tx_end`) | _TBD_ | -| `stop-network-slot` (`slot_chain_end`) | _TBD_ | -| Mesa genesis timestamp (UTC) | _TBD — exactly 3 hours after the stop-network-slot_ | -| State Finalization window | Exactly 100 slots = exactly 5 hours between `slot_tx_end` and `slot_chain_end` | +| Field | Value | +| --------------------------------------- | ------------------------------------------------------------------------------ | +| Pre-fork (stop-slot) release | _TBD — will be a `3.x.x` tag_ | +| Mesa release | _TBD — will be a `4.x.x` tag_ | +| `stop-transaction-slot` (`slot_tx_end`) | _TBD_ | +| `stop-network-slot` (`slot_chain_end`) | _TBD_ | +| Mesa genesis timestamp (UTC) | _TBD — exactly 3 hours after the stop-network-slot_ | +| State Finalization window | Exactly 100 slots = exactly 5 hours between `slot_tx_end` and `slot_chain_end` | Subscribe to the [MinaProtocol/mina releases](https://github.com/MinaProtocol/mina/releases?q=mesa) and watch the [Mina Foundation announcements channel](https://discord.gg/minaprotocol) for the schedule publication. @@ -4481,26 +4497,26 @@ Subscribe to the [MinaProtocol/mina releases](https://github.com/MinaProtocol/mi Devnet typically forks ahead of mainnet to give integrators a final dress rehearsal. Schedule will be posted here once announced. ::: -| Field | Value | -|---|---| -| Pre-fork (stop-slot) release | _TBD_ | -| Mesa release | _TBD_ | +| Field | Value | +| --------------------------------------- | ----- | +| Pre-fork (stop-slot) release | _TBD_ | +| Mesa release | _TBD_ | | `stop-transaction-slot` (`slot_tx_end`) | _TBD_ | -| `stop-network-slot` (`slot_chain_end`) | _TBD_ | -| Mesa genesis timestamp (UTC) | _TBD_ | +| `stop-network-slot` (`slot_chain_end`) | _TBD_ | +| Mesa genesis timestamp (UTC) | _TBD_ | ## Preflight The Mesa preflight network has already forked. The numbers below are historical; they will not change. -| Field | Value | -|---|---| -| Pre-fork release | `4.0.0-preflight1-b649c79` | -| Stop-slot release | `4.0.0-preflight-stop-2967b39` | -| Mesa release | `4.0.0-preflight-3f038cb` | -| Mesa hard-fork time (UTC) | 2026-04-27 13:00 | -| Transaction protocol version after fork | 5.0.0 | -| o1js version targeting protocol v5.0.0 | `o1js@3.0.0-mesa.698ca` | +| Field | Value | +| --------------------------------------- | ------------------------------ | +| Pre-fork release | `4.0.0-preflight1-b649c79` | +| Stop-slot release | `4.0.0-preflight-stop-2967b39` | +| Mesa release | `4.0.0-preflight-3f038cb` | +| Mesa hard-fork time (UTC) | 2026-04-27 13:00 | +| Transaction protocol version after fork | 5.0.0 | +| o1js version targeting protocol v5.0.0 | `o1js@3.0.0-mesa.698ca` | For the full preflight context, see [Preflight Network](/network-upgrades/mesa/preflight-network). @@ -4623,23 +4639,34 @@ The official ledger checkpoint published with the [Mesa release](#mesa-release). ## Mesa-Specific Changes and Conventions -Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavior. Full descriptions live in the [Mesa overview](/network-upgrades/mesa#what-mesa-introduces); the brief definitions below link each to its canonical spec. +Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavior. The canonical MIP specs live in the [MinaProtocol/MIPs](https://github.com/MinaProtocol/MIPs/tree/main/MIPS) repository; each section below links to the spec for the proposal it describes. -### Faster Blocks +### Faster Blocks — [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md) -Mesa reduces the slot time to 90 seconds and unsets the default zkApp soft limit (previously 24 commands per block). Defined in [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md). +Mesa halves Mina's slot time from **180 seconds to 90 seconds**, doubling block production frequency. To keep the long-term token emission rate flat, the per-block **coinbase reward is also halved** (from 720 MINA to 360 MINA). The total Mina supplied per epoch is unchanged. -### Expanded zkApp State +Several second-order consequences flow from the slot-time change: -Mesa increases the on-chain state available to zkApps from 8 fields (indexes `0–7`) to 32 fields (indexes `0–31`) per account. This applies to both the `zkapp_states` and `zkapp_states_nullable` database tables. Defined in [MIP7](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0007-increase-state-size-limit.md). See [Archive Node Schema Changes](/network-upgrades/mesa/appendix/archive-node-schema-changes) for the SQL diff. +- **Epoch duration halves** from ~14.9 days to ~7.4 days. Scripts and operational procedures tied to epoch boundaries (delegation cooldown, automated payouts, monitoring dashboards) trigger about twice as often. +- **Vesting schedules on active vesting accounts are automatically migrated** during the hard fork so they continue unlocking on the same real-world cadence. No operator action is required. +- **The zkApp per-block command soft limit is lowered** from 24 to 12, ensuring SNARK workers can keep up with the faster 90-second block cadence. This change is delivered via soft fork before Mesa. +- **SNARK coordinators handling maximum-cost zkApp transactions should deploy at least 4 workers** (≈4 CPU cores each) to keep up with the new 90-second slot timing. A prerequisite SNARK-worker parallelization is delivered via soft fork before Mesa. -### Larger Events and Actions +### Expanded zkApp State — [MIP7](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0007-increase-state-size-limit.md) + +Mesa raises the on-chain state available to a zkApp account from **8 field elements (indexes `0–7`) to 32 field elements (indexes `0–31`)**. zkApps can now store roughly four times more data directly on chain without off-chain workarounds. This applies to both the `zkapp_states` and `zkapp_states_nullable` database tables. See [Archive Node Schema Changes](/network-upgrades/mesa/appendix/archive-node-schema-changes) for the SQL diff. -Mesa raises the per-transaction limit on events and actions from 100 to 1024 field elements each, and removes the previous 16-field-element cap per individual event or action. Defined in [MIP8](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0008-increase-events-actions-limit.md). +### Larger Events and Actions — [MIP8](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0008-increase-events-actions-limit.md) + +Mesa raises the per-transaction limit on events and actions from **100 field elements to 1024 field elements** for each. The previous cap of 16 field elements per individual event or action is also removed. This makes events and actions a viable channel for richer on-chain signaling and larger off-chain dispatch payloads in a single transaction. + +Mostly relevant to zkApp developers — node operators do not need to act on this change, but block producers will validate against the new limits automatically after the fork. + +### Larger zkApp Transactions — [MIP9](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0009-increase-zkapp-account-update-limit.md) -### Larger zkApp Transactions +Mesa **roughly triples** the maximum number of account updates a single zkApp transaction can contain. The previous weighted-cost formula (`10.26·np + 10.08·n2 + 9.14·n1 < 69.45`) is replaced with a simpler `np + n2 + n1 ≤ 16` rule that admits any balanced binary proof tree of height 4. -Mesa roughly triples the maximum number of account updates a single zkApp transaction can contain. Defined in [MIP9](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0009-increase-zkapp-account-update-limit.md). +This depends on the SNARK-worker parallelization shipped as a prerequisite for [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md) — without it, processing maximum-size transactions inside a 90-second slot would not be feasible. ### Mesa Package Naming Convention @@ -4663,37 +4690,16 @@ This documentation uses terms like _automode_, _stop-slot_, _trustless upgrade_, ## What Mesa Introduces -Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavior, plus two operational improvements to the upgrade flow itself. The canonical MIP specs live in the [MinaProtocol/MIPs](https://github.com/MinaProtocol/MIPs/tree/main/MIPS) repository; each section below links to the spec for the proposal it describes. +Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavior, plus two operational improvements to the upgrade flow itself. See the **[Glossary](/network-upgrades/mesa/glossary)** for detailed descriptions of each MIP and the canonical specs in the [MinaProtocol/MIPs](https://github.com/MinaProtocol/MIPs/tree/main/MIPS) repository. -### Faster Blocks — [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md) - -Mesa halves Mina's slot time from **180 seconds to 90 seconds**, doubling block production frequency. To keep the long-term token emission rate flat, the per-block **coinbase reward is also halved** (from 720 MINA to 360 MINA). The total Mina supplied per epoch is unchanged. - -Several second-order consequences flow from the slot-time change: - -- **Epoch duration halves** from ~14.9 days to ~7.4 days. Scripts and operational procedures tied to epoch boundaries (delegation cooldown, automated payouts, monitoring dashboards) trigger about twice as often. -- **Vesting schedules on active vesting accounts are automatically migrated** during the hard fork so they continue unlocking on the same real-world cadence. No operator action is required. -- **SNARK coordinators handling maximum-cost zkApp transactions should deploy at least 4 workers** (≈4 CPU cores each) to keep up with the new 90-second slot timing. A prerequisite SNARK-worker parallelization is delivered via soft fork before Mesa. - -### Expanded zkApp State — [MIP7](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0007-increase-state-size-limit.md) - -Mesa raises the on-chain state available to a zkApp account from **8 field elements (indexes `0–7`) to 32 field elements (indexes `0–31`)**. zkApps can now store roughly four times more data directly on chain without off-chain workarounds. - -### Larger Events and Actions — [MIP8](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0008-increase-events-actions-limit.md) - -Mesa raises the per-transaction limit on events and actions from **100 field elements to 1024 field elements** for each. The previous cap of 16 field elements per individual event or action is also removed. This makes events and actions a viable channel for richer on-chain signaling and larger off-chain dispatch payloads in a single transaction. - -Mostly relevant to zkApp developers — node operators do not need to act on this change, but block producers will validate against the new limits automatically after the fork. - -### Larger zkApp Transactions — [MIP9](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0009-increase-zkapp-account-update-limit.md) - -Mesa **roughly triples** the maximum number of account updates a single zkApp transaction can contain. The previous weighted-cost formula (`10.26·np + 10.08·n2 + 9.14·n1 < 69.45`) is replaced with a simpler `np + n2 + n1 ≤ 16` rule that admits any balanced binary proof tree of height 4. - -This depends on the SNARK-worker parallelization shipped as a prerequisite for [MIP6](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0006-slot-reduction-90s.md) — without it, processing maximum-size transactions inside a 90-second slot would not be feasible. +- **[Faster Blocks — MIP6](/network-upgrades/mesa/glossary#faster-blocks)** — Halves slot time to 90 seconds, halves coinbase reward, halves epoch duration. +- **[Expanded zkApp State — MIP7](/network-upgrades/mesa/glossary#expanded-zkapp-state)** — Raises on-chain state from 8 to 32 field elements per zkApp account. +- **[Larger Events and Actions — MIP8](/network-upgrades/mesa/glossary#larger-events-and-actions)** — Increases per-transaction event/action limit from 100 to 1024 field elements. +- **[Larger zkApp Transactions — MIP9](/network-upgrades/mesa/glossary#larger-zkapp-transactions)** — Triples the max account updates per zkApp transaction. ### Automode Upgrades -For the first time in Mina's history, block producers can upgrade through a hard fork **without manual intervention**. The automode mechanism ships both the pre-fork and post-fork binaries in a single package, with a dispatcher that automatically transitions to the new chain when the fork activates. Archive node and Rosetta API operators still use manual mode — automode is not available for those node types. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for details. +For the first time in Mina's history, block producers can upgrade through a hard fork **without manual intervention**. The automode mechanism ships both the pre-fork and post-fork binaries in a single package, with a dispatcher that automatically transitions to the new chain when the fork activates. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for details, including which node types do not support automode. ### Simplified Archive Upgrade @@ -4721,78 +4727,29 @@ The upgrade moves through four phases — **Pre-Upgrade**, **State Finalization* > **Goal:** Every participant is prepared and running the stop-slot release before the fork begins. -The table below is a high-level summary. The concrete install commands (Debian, Docker, etc.) and hardware requirements live in the [Requirements](/network-upgrades/mesa/requirements) and [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) pages — start there once you know your role and deployment style. - -| Actor | What to do | -|---|---| -| **All operators** | Verify [hardware requirements](/network-upgrades/mesa/requirements) (32 GB RAM, 8-core CPU with AVX/BMI2). Back up keys. | -| **Block Producers** | Choose [upgrade mode](/network-upgrades/mesa/upgrade-modes): **automode** (recommended) or manual. Install stop-slot release [3.x.x](https://github.com/MinaProtocol/mina/releases). If automode, install the `mina-{network}-automode` package — see [Installing automode](/network-upgrades/mesa/upgrade-modes#installing-automode). | -| **SNARK Coordinators** | A coordinator is a daemon node — follow the Block Producer path (automode or manual). | -| **Standalone SNARK Workers** | Workers spawned by a coordinator (`--run-snark-worker`) need no separate action — they inherit the coordinator's binary. Workers run as a separate `mina internal snark-worker` process or container must be redeployed with the Mesa release after the fork. | -| **Archive Nodes** | Install stop-slot release. Choose upgrade method: _trustless_ (run upgrade script now) or _trustful_ (import o1Labs dump later). If trustless, run the [archive upgrade script](/network-upgrades/mesa/archive-upgrade) — it is backward compatible and can be applied early. | -| **Exchanges** | Install stop-slot release. Update integrations (mina-signer, Rosetta API). Test on devnet. Plan deposit/withdrawal freeze window. | -| **zkApp Developers** | Update to the Mesa-compatible o1js version (`o1js@3.0.0-mesa.698ca` for the preflight chain), recompile your contract, and verify it on the [preflight network](/network-upgrades/mesa/preflight-network). Plan to redeploy on Mesa after the fork — every zkApp must be redeployed because the protocol version bump changes the verification key. {/* TODO(PR #1133): Link to the official o1js Mesa upgrade guide once published (cjjdespres #3220525842). */} | - -:::tip Readiness checklist -Review the [Requirements](/network-upgrades/mesa/requirements) and pick your [Upgrade Mode](/network-upgrades/mesa/upgrade-modes) before proceeding. -::: - ---- +Each actor type has a specific checklist — see **[Requirements](/network-upgrades/mesa/requirements)** for the full per-actor pre-upgrade procedures and hardware requirements. ### Phase 2: State Finalization — hours before the fork (exactly 5 hours) > **Goal:** The network reaches consensus on a final state. No new transactions are accepted. -At the predefined [**stop-transaction-slot**](/network-upgrades/mesa/fork-schedule), nodes stop accepting new user transactions. Block production continues for ~100 more slots with empty blocks (no coinbase, no fees) until the [**stop-network-slot**](/network-upgrades/mesa/fork-schedule) to ensure all nodes converge on the same state. The concrete slot numbers and timestamps live on the [Fork Schedule](/network-upgrades/mesa/fork-schedule) page. - -| Actor | What to do | -|---|---| -| **Block Producers** | **Keep your node running.** Block density during finalization is critical. Do not stop your node. | -| **SNARK Workers** | **Keep running.** Continue producing SNARK work. | -| **Archive Nodes** | Keep the archive node running to capture all finalized blocks. If doing trustless upgrade, run the upgrade script now if you haven't already. | -| **Exchanges** | **Disable MINA deposits and withdrawals.** Any transactions submitted after the stop-transaction-slot will not exist on the Mesa chain. | -| **zkApp Developers** | No action required. Monitor announcements. | - -:::danger For exchanges -Transactions submitted after the stop-transaction-slot **will not carry over** to the Mesa chain. Freeze all MINA activity before this point. -::: - ---- +At the predefined **stop-transaction-slot**, nodes stop accepting new user transactions. Block production continues for ~100 more slots with empty blocks until the **stop-network-slot**. See **[State Finalization](/network-upgrades/mesa/upgrade-steps/state-finalization)** for the full per-actor instructions. ### Phase 3: Upgrade — fork day (network is down) > **Goal:** The network halts, state is exported, and the Mesa release is published. -At the **stop-network-slot**, block production stops entirely. o1Labs exports the network state, builds the Mesa release with the final ledger baked in, and publishes packages and Docker images. - -| Actor | What to do | -|---|---| -| **Block Producers (automode)** | **Nothing.** Your node transitions to Mesa automatically. It will start producing blocks when the Mesa genesis timestamp arrives. | -| **Block Producers (manual)** | Stop your node. Wait for the Mesa release announcement. Install the new package. Restart with [updated flags](/network-upgrades/mesa/upgrade-steps/post-upgrade). | -| **SNARK Coordinators** | Same as block producers — automode transitions automatically, manual requires stop + install + restart. | -| **Standalone SNARK Workers** | Coordinator-spawned workers follow the coordinator automatically. Standalone workers (`mina internal snark-worker` process or container) must be stopped and redeployed with the Mesa binary; an older worker cannot submit work to a Mesa coordinator. | -| **Archive Nodes** | Install the Mesa archive node release. Point it at your upgraded database (trustless) or import the o1Labs SQL dump into a fresh database (trustful). | -| **Exchanges** | Install the Mesa release. Keep deposits/withdrawals disabled until Mesa block production begins. | - ---- +At the **stop-network-slot**, block production stops entirely. o1Labs exports the network state, builds the Mesa release, and publishes packages. See **[Fork Schedule](/network-upgrades/mesa/fork-schedule)** for the schedule values and **[Upgrade](/network-upgrades/mesa/upgrade-steps/upgrade)** for the per-actor instructions. ### Phase 4: Post-Upgrade — after the fork > **Goal:** Block production resumes on the Mesa network. Normal operations return. -Exactly **3 hours** after the _stop-network-slot_, at the predefined Mesa genesis timestamp, the first Mesa block is produced. - -| Actor | What to do | -|---|---| -| **Block Producers** | Verify your node is on the Mesa chain (`mina client status`). If automode, check that the `activated` file exists in your config directory (see [Troubleshooting](/network-upgrades/mesa/troubleshooting#how-do-i-know-which-binary-my-node-is-using)). Monitor block production. | -| **SNARK Workers** | Reconnect workers to the upgraded coordinator. Standalone workers must already be on the Mesa binary at this point. Verify SNARK work is being produced. | -| **Archive Nodes** | Verify the archive database is in sync. Run [validation checks](/network-upgrades/mesa/upgrade-steps/post-upgrade#in-depth-validation). Fix any missing blocks using archive tooling. | -| **Exchanges** | **Re-enable MINA deposits and withdrawals** once block production is confirmed and your systems are verified. | -| **zkApp Developers** | **Redeploy every zkApp** on Mesa — the protocol version bump invalidates Berkeley verification keys, so a redeploy is required before any zkApp can accept transactions. You can also take advantage of the expanded 32-field on-chain state at this point. | +Exactly **3 hours** after the _stop-network-slot_, at the predefined Mesa genesis timestamp, the first Mesa block is produced. See **[Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade)** for verification checklists. --- -For step-by-step instructions per phase, see [Upgrade Steps](/network-upgrades/mesa/upgrade-steps). For end-to-end walkthroughs by role (block producer, archive node, zkApp developer, exchange), see [Examples](/network-upgrades/mesa/upgrade-steps/examples). +For end-to-end walkthroughs by role (block producer, archive node, zkApp developer, exchange), see **[Examples](/network-upgrades/mesa/upgrade-steps/examples)**. ## Upgrade Modes @@ -4800,18 +4757,15 @@ The Mesa upgrade supports two modes for daemon node operators: **[Automode](/net See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for the full comparison, requirements, and the persistent-filesystem / process-restart constraints that automode imposes. For low-level details on the dispatcher and dual-binary architecture, see [Upgrade Modes — Details](/network-upgrades/mesa/appendix/upgrade-modes-details). -## Examples - -End-to-end walkthroughs of the four phases for different roles (block producer automode/manual, archive node, zkApp developer, exchange) live on the [Examples](/network-upgrades/mesa/upgrade-steps/examples) page. ## Quick Reference by Operator Type | Operator Type | Key Pages | |---|---| -| **Block Producers** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Modes](/network-upgrades/mesa/upgrade-modes), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade Flags](/network-upgrades/mesa/upgrade-steps/post-upgrade) | -| **SNARK Workers / Coordinators** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade Flags](/network-upgrades/mesa/upgrade-steps/post-upgrade) | -| **Archive Node Operators** | [Requirements](/network-upgrades/mesa/requirements), [Archive Upgrade](/network-upgrades/mesa/archive-upgrade), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) | -| **Rosetta API Operators** | [Requirements](/network-upgrades/mesa/requirements), [Archive Upgrade](/network-upgrades/mesa/archive-upgrade), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) | -| **Exchanges** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade), [Archive Node Schema Changes](/network-upgrades/mesa/appendix/archive-node-schema-changes) | +| **Block Producers** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Modes](/network-upgrades/mesa/upgrade-modes), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps) | +| **SNARK Workers / Coordinators** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps) | +| **Archive Node Operators** | [Requirements](/network-upgrades/mesa/requirements), [Archive Upgrade](/network-upgrades/mesa/archive-upgrade), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps) | +| **Rosetta API Operators** | [Requirements](/network-upgrades/mesa/requirements), [Archive Upgrade](/network-upgrades/mesa/archive-upgrade), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps) | +| **Exchanges** | [Requirements](/network-upgrades/mesa/requirements), [Upgrade Steps](/network-upgrades/mesa/upgrade-steps), [Archive Node Schema Changes](/network-upgrades/mesa/appendix/archive-node-schema-changes) | ## Network Details @@ -4837,9 +4791,9 @@ https://github.com/MinaProtocol/mina/releases?q=mesa url: /network-upgrades/mesa/preflight-network --- -# Connect to Mesa Preflight Network +# Mesa Preflight Network -The Mesa preflight network is a testing environment for validating the Mesa upgrade before deployment to devnet and mainnet. This network allows node operators and developers to test their infrastructure and applications with the new Mesa release. +The Mesa preflight network is a testing environment for validating the Mesa upgrade before deployment to devnet and mainnet. For step-by-step connection instructions, see [Preflight Setup](/network-upgrades/mesa/preflight-setup). :::tip Mesa preflight hard fork completed @@ -4849,20 +4803,10 @@ The transaction protocol bump is a breaking wire-format change: any node still r zkApp developers must rebuild and redeploy against **`o1js@3.0.0-mesa.698ca`** — the first o1js release that targets transaction protocol v5.0.0. Transactions produced by earlier o1js versions will be rejected by post-fork nodes. -A dedicated **Upgrade Steps** page covering the post-fork operator checklist will be linked from the Mesa Upgrade sidebar once it ships. - -::: - -:::caution Preflight Network Notice - -The preflight network is intended for testing purposes only. This network may experience instability, breaking changes, and unexpected behavior. Data on this network should not be considered persistent or reliable. - ::: ## Available Build Versions -The Mesa preflight network uses the following build versions: - **Current version (install this):** `4.0.0-preflight-3f038cb` — post-hard-fork release. Implements transaction protocol version **5.0.0** and is the only build compatible with the post-fork chain. **Compatible o1js release:** `o1js@3.0.0-mesa.698ca` — the matching SDK for transaction protocol v5.0.0. Install with `npm install o1js@3.0.0-mesa.698ca` (or the equivalent for your package manager) when developing or redeploying zkApps against the post-fork preflight network. @@ -4872,7 +4816,7 @@ The Mesa preflight network uses the following build versions: - `4.0.0-preflight-stop-2967b39` — stop-slot release used to carry nodes up to the fork. Pre-fork transaction protocol; incompatible with the post-fork chain. - `4.0.0-preflight1-b649c79` — original preflight build. Listed for reference only. -### Docker Images +## Docker Images Docker images are available for both `amd64` and `arm64` architectures, on the `bookworm` and `noble` base distributions: @@ -4882,7 +4826,7 @@ Docker images are available for both `amd64` and `arm64` architectures, on the ` For `noble`, swap `bookworm` for `noble` in the tag (e.g. `mina-daemon:4.0.0-preflight-3f038cb-noble-mesa`). -### Debian Packages +## Debian Packages Debian packages are available from the unstable repository: @@ -4898,21 +4842,49 @@ Available packages (each at version `4.0.0-preflight-3f038cb`): For detailed information about the Debian repository structure and configuration, please refer to the [Debian Repository documentation](https://unstable.apt.packages.minaprotocol.com/). -## Connecting to the Network +## Nightly Builds -To connect your node to the Mesa preflight network, you must use the preflight network seed peer list. +In addition to the preflight release builds, nightly builds are also available for testing the latest changes. -### Required Parameter +**Repository:** `nightly.apt.packages.minaprotocol.com` + +Nightly builds are available for both Debian packages and Docker images. These builds represent the latest development state and may be even more unstable than preflight releases. -Add the following parameter to your mina daemon command: +For more information about nightly builds and repository configuration, see the [Debian Repository documentation](https://nightly.apt.packages.minaprotocol.com/). + +## Next Steps + +- [Connect to the Preflight Network](/network-upgrades/mesa/preflight-setup) — Docker and Debian setup guides +- [Mesa Upgrade Overview](/network-upgrades/mesa) — prepare for mainnet + +--- +url: /network-upgrades/mesa/preflight-setup +--- + +# Connect to Mesa Preflight Network + +The Mesa preflight network is a testing environment for validating the Mesa upgrade before deployment to devnet and mainnet. This page walks through connecting each node type. + +Before starting, check the [Preflight Network](/network-upgrades/mesa/preflight-network) page for the current build versions, Docker image tags, and Debian package names. + +:::caution Preflight Network Notice + +The preflight network is intended for testing purposes only. This network may experience instability, breaking changes, and unexpected behavior. Data on this network should not be considered persistent or reliable. + +::: + +## Connecting to the Network + +All node types must use the preflight network seed peer list: ```bash --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt ``` -### Example: Running with Docker + + -To start a Mina daemon node using Docker: +### Mina Daemon ```bash docker run --name mina-mesa-preflight -d \ @@ -4923,7 +4895,7 @@ docker run --name mina-mesa-preflight -d \ --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt ``` -For production deployments, you'll want to mount configuration directories and add additional flags: +For production deployments, mount config directories and add additional flags: ```bash docker run --name mina-mesa-preflight -d \ @@ -4936,7 +4908,36 @@ docker run --name mina-mesa-preflight -d \ --libp2p-keypair /data/.mina-config/keys/libp2p-key ``` -### Example: Running with Debian Package +### Archive Node + +```bash +docker run --name mina-archive-mesa -d \ + -p 3086:3086 \ + --restart=always \ + gcr.io/o1labs-192920/mina-archive:4.0.0-preflight-3f038cb-bookworm-mesa \ + mina-archive run \ + --postgres-uri postgresql://archive_user:your-secure-password@postgres-host:5432/archive \ + --server-port 3086 +``` + +If upgrading an existing Berkeley database, see [Archive Upgrade](/network-upgrades/mesa/archive-upgrade). + +### Rosetta API + +```bash +docker run --name mina-rosetta-mesa -d \ + -p 3087:3087 \ + --restart=always \ + gcr.io/o1labs-192920/mina-rosetta:4.0.0-preflight-3f038cb-bookworm-mesa \ + --port 3087 \ + --archive-uri http://archive-host:3086/graphql \ + --graphql-uri http://mina-daemon-host:3085/graphql +``` + +**Note:** Rosetta requires a running Mina daemon (port 3085) and archive node (port 3086). Both must be fully synced. + + + First, install dependencies and configure the repository: @@ -4957,7 +4958,7 @@ sudo apt-get update sudo apt-get install -y mina-mesa=4.0.0-preflight-3f038cb ``` -Then start the daemon: +### Mina Daemon ```bash mina daemon \ @@ -4965,132 +4966,49 @@ mina daemon \ --libp2p-keypair ~/.mina-config/keys/libp2p-key ``` -### Running Archive Node - -:::info Upgrading from Berkeley to Mesa - -If you have an existing Berkeley archive database that you want to upgrade to Mesa, please refer to the comprehensive [Archive Upgrade](archive-upgrade) guide for detailed instructions on: -- Upgrade prerequisites and requirements -- Running the upgrade script -- Rollback procedures -- Database schema changes -- Verification steps - -::: - -#### Installing and Running Mesa Archive Node - -An archive node stores the full history of the blockchain and provides a GraphQL API for querying historical data. It requires a PostgreSQL database. - -**Installation with Debian:** +### Archive Node ```bash -# Step 1: Install dependencies -sudo apt-get install -y lsb-release ca-certificates wget gnupg postgresql postgresql-contrib - -# Step 2: Import the GPG key -wget -q https://unstable.apt.packages.minaprotocol.com/repo-signing-key.gpg \ - -O /etc/apt/trusted.gpg.d/minaprotocol.gpg - -# Step 3: Add the repository -echo "deb https://unstable.apt.packages.minaprotocol.com $(lsb_release -cs) preflight" | \ - sudo tee /etc/apt/sources.list.d/mina-preflight.list - -# Step 4: Install mina-archive-mesa -sudo apt-get update +# Install archive package sudo apt-get install -y mina-archive-mesa=4.0.0-preflight-3f038cb -# Step 5: Create PostgreSQL database +# Create PostgreSQL database (if needed) sudo -u postgres createdb archive sudo -u postgres createuser archive_user sudo -u postgres psql -c "ALTER USER archive_user WITH PASSWORD 'your-secure-password';" sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE archive TO archive_user;" -# Step 6: Start the archive node +# Start archive node mina-archive run \ --postgres-uri postgresql://archive_user:your-secure-password@localhost:5432/archive \ --server-port 3086 ``` -**Using Docker:** +If upgrading an existing Berkeley database, see [Archive Upgrade](/network-upgrades/mesa/archive-upgrade). -```bash -# Start the archive node (assumes you have a PostgreSQL server running) -docker run --name mina-archive-mesa -d \ - -p 3086:3086 \ - --restart=always \ - gcr.io/o1labs-192920/mina-archive:4.0.0-preflight-3f038cb-bookworm-mesa \ - mina-archive run \ - --postgres-uri postgresql://archive_user:your-secure-password@postgres-host:5432/archive \ - --server-port 3086 -``` - -**Connecting Mina Daemon to Archive:** - -Configure your mina daemon to send blocks to the archive node: - -```bash -mina daemon \ - --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt \ - --archive-address localhost:3086 -``` - -### Installing and Running Rosetta - -Rosetta is a standardized API for blockchain integration. The Rosetta API requires both a mina daemon and an archive node. - -**Installation with Debian:** +### Rosetta API ```bash -# Step 1: Install dependencies (if not already done) -sudo apt-get install -y lsb-release ca-certificates wget gnupg - -# Step 2: Import the GPG key (if not already done) -wget -q https://unstable.apt.packages.minaprotocol.com/repo-signing-key.gpg \ - -O /etc/apt/trusted.gpg.d/minaprotocol.gpg - -# Step 3: Add the repository (if not already done) -echo "deb https://unstable.apt.packages.minaprotocol.com $(lsb_release -cs) preflight" | \ - sudo tee /etc/apt/sources.list.d/mina-preflight.list - -# Step 4: Install mina-rosetta-mesa -sudo apt-get update sudo apt-get install -y mina-rosetta-mesa=4.0.0-preflight-3f038cb -# Step 5: Start Rosetta -# Rosetta connects to both the mina daemon and archive node mina-rosetta \ --port 3087 \ --archive-uri http://localhost:3086/graphql \ --graphql-uri http://localhost:3085/graphql ``` -**Using Docker:** - -```bash -docker run --name mina-rosetta-mesa -d \ - -p 3087:3087 \ - --restart=always \ - gcr.io/o1labs-192920/mina-rosetta:4.0.0-preflight-3f038cb-bookworm-mesa \ - --port 3087 \ - --archive-uri http://archive-host:3086/graphql \ - --graphql-uri http://mina-daemon-host:3085/graphql -``` - -**Note:** Rosetta requires: -- A running mina daemon (GraphQL endpoint, typically port 3085) -- A running archive node (GraphQL endpoint, typically port 3086) -- Both must be fully synced for Rosetta to function properly - -## Nightly Builds - -In addition to the preflight release builds, nightly builds are also available for testing the latest changes. + + -**Repository:** `nightly.apt.packages.minaprotocol.com` +### Connecting Mina Daemon to Archive -Nightly builds are available for both Debian packages and Docker images. These builds represent the latest development state and may be even more unstable than preflight releases. +Configure your daemon to send blocks to the archive node: -For more information about nightly builds and repository configuration, see the [Debian Repository documentation](https://nightly.apt.packages.minaprotocol.com/). +```bash +mina daemon \ + --peer-list-url https://storage.googleapis.com/o1labs-gitops-infrastructure/mina-mesa-network/mina-mesa-network-seeds.txt \ + --archive-address localhost:3086 +``` ## Verification @@ -5126,8 +5044,8 @@ If you encounter issues or have feedback about the Mesa preflight network: ## Next Steps -- Explore additional Mesa upgrade documentation - Test your applications and infrastructure against the preflight network +- Review the [Mesa Upgrade](/network-upgrades/mesa) overview for mainnet preparation - Provide feedback to help improve the Mesa upgrade process --- @@ -5173,6 +5091,49 @@ mina libp2p generate-keypair --privkey-path Further information on [generating a libp2p key pair](/node-operators/seed-peers/generating-a-libp2p-keypair) on Mina Protocol. +## Pre-Upgrade Checklist + +Before the fork, each actor type must complete specific preparations. Complete these steps **weeks before the fork** to ensure a smooth upgrade. + +### All operators + +- Verify your hardware meets the [requirements](#hardware-requirements) above (32 GB RAM, 8-core CPU with AVX/BMI2). +- Back up your keys and configuration before installing any new packages. + +### Block Producers + +- Choose your [Upgrade Mode](/network-upgrades/mesa/upgrade-modes): **automode** (recommended) or manual. +- Install the stop-slot release [3.x.x](https://github.com/MinaProtocol/mina/releases). +- If using automode, install the `mina-{network}-automode` package. See [Installing automode](/network-upgrades/mesa/upgrade-modes#installing-automode). + +### SNARK Coordinators + +- A coordinator is a daemon node — follow the Block Producer path above (automode or manual). + +### Standalone SNARK Workers + +- Workers spawned by a coordinator (`--run-snark-worker`) need no separate action — they inherit the coordinator's binary. +- Workers run as a separate `mina internal snark-worker` process or container must be redeployed with the Mesa release after the fork. + +### Archive Nodes + +- Install the stop-slot release. +- Choose your upgrade method: [_trustless_](/network-upgrades/mesa/glossary#trustless) (run the upgrade script now) or [_trustful_](/network-upgrades/mesa/glossary#trustful) (import o1Labs dump later). +- If doing trustless, run the [Archive Upgrade](/network-upgrades/mesa/archive-upgrade) script — it can be applied before the fork while the Berkeley archive node is still running. + +### Exchanges + +- Install the stop-slot release. +- Update integrations (mina-signer, Rosetta API). +- Test on devnet. +- Plan your deposit/withdrawal freeze window around the [`stop-transaction-slot`](/network-upgrades/mesa/glossary#stop-transaction-slot). + +### zkApp Developers + +- Update to the Mesa-compatible o1js version (`o1js@3.0.0-mesa.698ca` for the preflight chain). +- Recompile your contracts and verify them on the [preflight network](/network-upgrades/mesa/preflight-network). +- Plan to redeploy every zkApp on Mesa — each must be redeployed because the protocol version bump changes the verification key. {/* TODO(PR #1133): Link to the official o1js Mesa upgrade guide once published (cjjdespres #3220525842). */} + --- url: /network-upgrades/mesa/troubleshooting --- @@ -5466,12 +5427,12 @@ mina client status ``` :::note Dispatcher and non-daemon commands -The automode dispatcher only supports the `daemon` subcommand and `client status` command — it cannot determine the active runtime for other commands because they don't pass the config directory. For commands like `accounts list`, or `ledger export`, use the correct version-specific binary directly: `mina-mesa` (after the fork) or `mina-berkeley` (before the fork). The full paths `/usr/lib/mina/mesa/mina` and `/usr/lib/mina/berkeley/mina` also work. This limitation may be removed in a future release. +The automode dispatcher only supports `daemon` and `client status` subcommands. For other commands, use `mina-mesa` or `mina-berkeley` directly. See [Troubleshooting](/network-upgrades/mesa/troubleshooting#can-i-run-non-daemon-commands-or-use-a-specific-binary-version) for details. ::: She's done. Her node is producing blocks on Mesa. -> For post-upgrade flags and monitoring, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade). +> For post-upgrade verification, monitoring, and flag reference, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference).
@@ -5534,7 +5495,7 @@ docker run --name mina -d \ docker exec mina mina client status # confirms Mesa chain ID ``` -> For post-upgrade flags and monitoring, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade). +> For post-upgrade verification, monitoring, and flag reference, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference).
@@ -5684,7 +5645,7 @@ sudo apt-get install mina-mainnet=3.x.x **Hours before the fork** — Before the _stop-transaction-slot_ arrives, Bob **disables MINA deposits and withdrawals** on his platform and notifies customers about the maintenance window. :::danger -Any transactions submitted after the stop-transaction-slot **will not exist on the Mesa chain**. This is the most critical step for exchanges. +Any transactions submitted after the stop-transaction-slot **will not exist on the Mesa chain**. See [State Finalization](/network-upgrades/mesa/upgrade-steps/state-finalization#exchanges) for the full exchange guidance. ::: **Fork day** — The network halts. Bob waits for the Mesa release announcement, then upgrades: @@ -5705,7 +5666,7 @@ mina client status # verify Mesa chain ID # test a small internal transfer before opening to customers ``` -> For post-upgrade flags and configurations, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade). +> For post-upgrade verification, monitoring, and flag reference, see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference). @@ -5722,7 +5683,7 @@ The Mesa upgrade proceeds through four sequential phases. Each phase has specifi | [Pre-Upgrade](/network-upgrades/mesa/requirements) | Prepare infrastructure, upgrade to the stop-slot release, run archive upgrade scripts | | [State Finalization](/network-upgrades/mesa/upgrade-steps/state-finalization) | 100-slot stabilization period — no new transactions accepted, block production continues | | [Upgrade](/network-upgrades/mesa/upgrade-steps/upgrade) | Network halts, state is exported, Mesa build is published | -| [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) | Block production resumes on Mesa, flags and configurations for the new network | +| [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) | Block production resumes on Mesa — verification and health checks for the new network | **Please note:** A simplified Node Status service will be part of the upgrade tooling and enabled by default in the Pre-Upgrade release with stop-slots ([3.x.x](https://github.com/MinaProtocol/mina/releases)). This feature allows for a safe upgrade by monitoring the amount of upgraded active stake. Only non-sensitive data is reported. @@ -5736,7 +5697,7 @@ Role-specific quick references: - **Block Producers & SNARK Coordinators** — pick a mode on [Upgrade Modes](/network-upgrades/mesa/upgrade-modes). Install commands for automode are in [Upgrade Modes — Installing automode](/network-upgrades/mesa/upgrade-modes#installing-automode). - **SNARK Workers** — coordinator-spawned workers inherit the coordinator's binary; standalone `mina internal snark-worker` deployments must be redeployed with the Mesa binary after the fork. -- **Archive Node Operators** — archive nodes do **not** support automode. See [Archive Upgrade](/network-upgrades/mesa/archive-upgrade) for the schema upgrade and trustless/trustful paths. +- **Archive Node Operators** — Archive nodes do **not** support automode (see [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for limitations). See [Archive Upgrade](/network-upgrades/mesa/archive-upgrade) for the schema upgrade and trustless/trustful paths. - **Exchanges** — disable MINA deposits and withdrawals before the _stop-transaction-slot_ and keep them disabled until Mesa block production resumes. See [Exchanges](/network-upgrades/mesa/upgrade-steps/post-upgrade) on the Post-Upgrade page for the re-enable checklist. :::danger For exchanges @@ -5753,6 +5714,17 @@ Exactly 3 hours after the network reaches the _stop-network-slot_, at the predef This page helps you **verify your node is healthy** and running on the Mesa chain. +## Per-actor summary + +| Actor | During this phase | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Block Producers** | Verify your node is on the Mesa chain (`mina client status`). If using automode, check the `activated` file. Monitor block production. | +| **SNARK Workers** | Reconnect workers to the upgraded coordinator. Standalone workers must already be on the Mesa binary. Verify SNARK work is being produced. | +| **Archive Node Operators** | Verify the archive database is in sync. Run [validation checks](#in-depth-validation). Fix any missing blocks. | +| **Rosetta Operators** | Complete the archive node checks first, then verify Rosetta is responding. Run `rosetta-cli` validation. | +| **Exchanges** | **Re-enable MINA deposits and withdrawals** once block production is confirmed and your systems are verified end to end. | +| **zkApp Developers** | **Redeploy every zkApp** on Mesa — the protocol version bump invalidates Berkeley verification keys. Verify your contracts against o1js v3 / protocol v5. Use the expanded 32-field on-chain state. | + The checks are split into separate tabs for **Rosetta API** and **Exchange** because the two roles overlap but are not the same. _Rosetta API_ here means an operator running the `mina-rosetta` integration layer (typically alongside an archive node). _Exchange_ means an operator running the customer-facing platform that ingests Mina balances and submits payments. Most exchanges use Rosetta, so they will work through both tabs; a handful operate without Rosetta (custom GraphQL integrations) and can skip the Rosetta tab. ## Verify Your Node @@ -5768,6 +5740,7 @@ mina client status ``` You should see: + - **Sync status**: `Synced` - **Chain ID** matching the Mesa chain ID for your network. The chain ID changes at the fork and is network-specific (mainnet, devnet, and preflight each get their own) — the exact value is published in the Mesa release announcement alongside the first Mesa packages. - **Git SHA-1** matching the published Mesa daemon commit @@ -5851,6 +5824,8 @@ Rosetta depends on a healthy archive database. #### 2. Verify Rosetta is responding +For the full Rosetta API setup and verification guide, see [Rosetta API](/node-operators/data-and-history/rosetta). + ```bash curl -s http://localhost:3088/network/list \ -H 'Content-Type: application/json' \ @@ -5882,6 +5857,7 @@ curl -s http://localhost:3088/account/balance \ #### 2. Re-enable deposits and withdrawals Only re-enable MINA deposits and withdrawals after: + - Block production is confirmed (blocks are advancing) - Your integration is verified end to end - You have confirmed balances match expectations @@ -5897,11 +5873,13 @@ The checks in the tabs above cover basic health. This section provides deeper va 1. **Verify signature kind** — query the GraphQL endpoint to confirm the correct signature kind: + ```graphql query { signatureKind } ``` + For mainnet, this should return `mainnet`. 2. **Verify connectivity** — ensure your node has peers and is connected to the network. Check that the node is receiving and gossiping blocks. @@ -5912,6 +5890,7 @@ The checks in the tabs above cover basic health. This section provides deeper va Use the `mina-archive-hardfork-toolbox` to verify the upgrade. All commands require `--postgres-uri postgresql://:@:/`. See the [Archive Upgrade](/network-upgrades/mesa/archive-upgrade#verification-with-the-archive-hardfork-toolbox) page for full toolbox documentation. **Verify schema upgrade:** + ```bash mina-archive-hardfork-toolbox verify-upgrade \ --postgres-uri \ @@ -5920,11 +5899,13 @@ mina-archive-hardfork-toolbox verify-upgrade \ ``` You can also verify manually: + ```sql SELECT * FROM migration_history; ``` **Validate fork block integrity** (after the fork activates): + ```bash mina-archive-hardfork-toolbox validate-fork \ --postgres-uri \ @@ -5933,6 +5914,7 @@ mina-archive-hardfork-toolbox validate-fork \ ``` **Verify no commands after fork point:** + ```bash mina-archive-hardfork-toolbox fork-candidate no-commands-after \ --postgres-uri \ @@ -5941,20 +5923,24 @@ mina-archive-hardfork-toolbox fork-candidate no-commands-after \ ``` **Verify extended zkApp state columns exist:** + ```sql SELECT column_name FROM information_schema.columns WHERE table_name = 'zkapp_states_nullable' AND column_name LIKE 'element%' ORDER BY column_name; ``` + Confirm columns `element0` through `element31` exist. **Check for missing blocks:** + ```bash mina-missing-blocks-auditor --archive-uri postgres://:@
:/ ``` **Compare block heights** — the archive height should match or be close to the daemon's reported height: + ```sql SELECT MAX(height) FROM blocks; ``` @@ -6020,25 +6006,17 @@ The Node Status reporting service is **enabled by default** on the Mesa daemon. To opt out of the Node Status service entirely, pass `--disable-node-status` (no value). Note: the previously-documented `--node-stats-type full|none` argument was never accepted by the daemon — `--simplified-node-stats` and `--disable-node-status` are the actual flag names in the Mesa release. -## Report Issues - -If you encounter any problems after the upgrade: - -- Report bugs on [GitHub](https://github.com/MinaProtocol/mina/issues) with the label `mesa` -- Reach out on [Discord](https://discord.gg/minaprotocol) in the appropriate channel - ---- - ## Flag and Configuration Reference The flags below are **unchanged from Berkeley** — if your node was running correctly before the fork, the same flags will work on Mesa. This section is provided as a reference for operators setting up fresh nodes or verifying their configuration. -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`). */} +For the canonical flag reference, see the [Validator Node docs](/node-operators/validator-node/connecting-to-the-network), [Block Producer docs](/node-operators/block-producer-node/getting-started), [SNARK Worker docs](/node-operators/snark-workers/getting-started), and [Archive Node docs](/node-operators/archive-node). :::info What changed in Mesa + - **Only if you manually manage your genesis config or genesis ledgers, repoint `--genesis-ledger-dir` and `-config-file` at the Mesa-specific files.** Operators who rely on the package-installed genesis config — including all automode users — do not need to change anything. If you do override them, 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`). - **All other flags carry over unchanged** — `--block-producer-key`, `--libp2p-keypair`, `--peer-list-url`, `--external-ip/port`, log flags, etc. behave the same on Mesa as on Berkeley. -::: + :::
Block Producer flags @@ -6063,6 +6041,8 @@ ENVIRONMENT VARIABLES
SNARK Coordinator flags +For detailed flag descriptions, see [SNARK Workers — Getting Started](/node-operators/snark-workers/getting-started). + ``` mina daemon --config-directory @@ -6084,6 +6064,8 @@ ENVIRONMENT VARIABLES
SNARK Worker flags +For detailed flag descriptions, see [SNARK Workers — Getting Started](/node-operators/snark-workers/getting-started). + ``` mina internal snark-worker --proof-level full @@ -6151,6 +6133,13 @@ docker run \
+## Report Issues + +If you encounter any problems after the upgrade: + +- Report bugs on [GitHub](https://github.com/MinaProtocol/mina/issues) with the label `mesa` +- Reach out on [Discord](https://discord.gg/minaprotocol) in the appropriate channel + --- url: /network-upgrades/mesa/upgrade-steps/state-finalization --- @@ -6163,6 +6152,17 @@ During the state finalization slots, it is crucial to maintain a high block dens Archive nodes should also continue to execute to ensure finalized blocks are in the database and can be carried over to the upgraded schema, preserving the integrity and accessibility of the network's history. +## Per-actor summary + +| Actor | During this phase | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Block Producers** | Keep your node running. Block density during finalization is critical — do not stop your node. Both automode and manual operators simply keep running. | +| **SNARK Workers** | Continue producing SNARK work. No special action required. | +| **Archive Node Operators** | Keep the archive node running to capture all finalized blocks. If doing trustless upgrade, run the [archive upgrade script](/network-upgrades/mesa/archive-upgrade) now if not done already. | +| **Rosetta Operators** | Follow the archive node instructions — keep your archive node running. | +| **Exchanges** | **Disable MINA deposits and withdrawals.** Any transactions submitted after the stop-transaction-slot will not carry over to the Mesa chain. | +| **zkApp Developers** | No action required. Monitor announcements for the Mesa genesis timestamp. | + ## 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. @@ -6180,7 +6180,7 @@ During this phase, both Automode and Manual mode operators simply keep their nod If you are doing the trustless upgrade, 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. +2. Execute the [archive node upgrade script](/network-upgrades/mesa/archive-upgrade). It can be applied before the fork. 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](/network-upgrades/mesa/archive-upgrade) section. @@ -6200,6 +6200,18 @@ Starting at the _stop-network-slot_ the network will not produce nor accept new There is a tool available to validate that the Mesa node was built from the pre-upgrade network state. See [In-Depth Validation](/network-upgrades/mesa/upgrade-steps/post-upgrade#in-depth-validation) for the `mina-archive-hardfork-toolbox` commands (`validate-fork`, `fork-candidate no-commands-after`) used to verify fork-block integrity. {/* TODO(PR #1133): If/when an authoritative `upgrading-to-mesa.md` lands in MinaProtocol/mina, link to it here. The previous link to `mina/blob/mesa/docs/upgrading-to-mesa.md` returned 404 — the `mesa` branch does not exist on the main repo. */} +## Per-actor summary + +| Actor | During this phase | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Block Producers (automode)** | Nothing. Your node transitions to Mesa automatically and will start producing blocks at the Mesa genesis timestamp. | +| **Block Producers (manual)** | Stop your node. Wait for the Mesa release announcement, then install the new package and restart with [updated flags](/network-upgrades/mesa/upgrade-steps/post-upgrade). | +| **SNARK Coordinators** | Same as block producers — automode transitions automatically; manual requires stop, install, and restart. | +| **Standalone SNARK Workers** | Stop old workers. After the Mesa release is published, redeploy and start workers against the Mesa coordinator — an older worker cannot submit work to a Mesa coordinator. | +| **Archive Node Operators** | Install the Mesa archive node release. Point it at your upgraded database (trustless) or import the o1Labs SQL dump (trustful). | +| **Rosetta Operators** | Follow the archive node upgrade procedure for your archive database. Install the Mesa Rosetta release when published. | +| **Exchanges** | Install the Mesa release if running node infrastructure. **Keep deposits/withdrawals disabled** until block production is confirmed on the Mesa chain (see [Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade)). | + ## Block Producers and SNARK Workers :::info @@ -6209,8 +6221,8 @@ If you are using [Automode](/network-upgrades/mesa/upgrade-modes), your node han If you are using **Manual mode**: 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. Pass it to the Mesa daemon with the [`--libp2p-keypair`](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference) flag (see the Flag and Configuration Reference on the Post-Upgrade page). +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 Mesa genesis timestamp, which is when the first Mesa block will be produced. +3. It is possible to continue using the same libp2p key after the upgrade. Pass it to the Mesa daemon with the [`--libp2p-keypair`](/node-operators/block-producer-node/getting-started) flag. All daemon flags carry over unchanged from Berkeley — see the [Post-Upgrade flag reference](/network-upgrades/mesa/upgrade-steps/post-upgrade#flag-and-configuration-reference) for the full per-role configuration. ## Archive Node Operators and Rosetta Operators