From da6dd1fcb6d948ae01d339718cd41162039365ee Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 15:24:07 +0700 Subject: [PATCH 01/12] Restructure Mesa docs: move MIP detail to glossary, thin index phase tables to one-liners --- docs/network-upgrades/mesa/glossary.mdx | 28 +++++--- docs/network-upgrades/mesa/index.mdx | 93 +++---------------------- 2 files changed, 29 insertions(+), 92 deletions(-) diff --git a/docs/network-upgrades/mesa/glossary.mdx b/docs/network-upgrades/mesa/glossary.mdx index f55ab7afb..222ffbd13 100644 --- a/docs/network-upgrades/mesa/glossary.mdx +++ b/docs/network-upgrades/mesa/glossary.mdx @@ -120,23 +120,33 @@ 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. +- **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..444061682 100644 --- a/docs/network-upgrades/mesa/index.mdx +++ b/docs/network-upgrades/mesa/index.mdx @@ -21,33 +21,12 @@ 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 @@ -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 **[Upgrade](/network-upgrades/mesa/upgrade-steps/upgrade)** for the full per-actor instructions and fork schedule. ### 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,9 +88,6 @@ 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 | From c00cc9bc785b548f5c2dc3f8f9771cce08630481 Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 15:24:56 +0700 Subject: [PATCH 02/12] Split preflight-network.mdx: lean version reference + new preflight-setup.mdx for tutorials --- .../mesa/preflight-network.mdx | 245 +----------------- .../network-upgrades/mesa/preflight-setup.mdx | 202 +++++++++++++++ 2 files changed, 211 insertions(+), 236 deletions(-) create mode 100644 docs/network-upgrades/mesa/preflight-setup.mdx 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 From 80ce8413ee3c8301fd463370b071e47dc0dd9a18 Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 15:25:13 +0700 Subject: [PATCH 03/12] De-duplicate preflight callout: centralize in preflight-network.mdx, link from archive-upgrade and parent index --- docs/network-upgrades/index.mdx | 10 ++-------- docs/network-upgrades/mesa/archive-upgrade.mdx | 6 ++---- 2 files changed, 4 insertions(+), 12 deletions(-) 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..da6d57fc0 100644 --- a/docs/network-upgrades/mesa/archive-upgrade.mdx +++ b/docs/network-upgrades/mesa/archive-upgrade.mdx @@ -15,11 +15,9 @@ keywords: 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. ::: From 37b5fa17ab13d297bfaa5e63a6bb4cd6071a50c8 Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 15:25:43 +0700 Subject: [PATCH 04/12] Merge fork-schedule.mdx into upgrade-steps/upgrade.mdx; delete fork-schedule --- docs/network-upgrades/mesa/fork-schedule.mdx | 77 ------------------- .../mesa/upgrade-steps/upgrade.mdx | 70 ++++++++++++++++- 2 files changed, 67 insertions(+), 80 deletions(-) delete mode 100644 docs/network-upgrades/mesa/fork-schedule.mdx diff --git a/docs/network-upgrades/mesa/fork-schedule.mdx b/docs/network-upgrades/mesa/fork-schedule.mdx deleted file mode 100644 index 326a3b17b..000000000 --- a/docs/network-upgrades/mesa/fork-schedule.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Mesa Fork Schedule -sidebar_label: Fork Schedule -hide_title: true -description: Concrete fork-schedule values for the Mesa upgrade — Mesa genesis timestamp, stop-transaction-slot (slot_tx_end), stop-network-slot (slot_chain_end), and pre-fork / Mesa release versions per network. -keywords: - - Mesa - - fork schedule - - stop-transaction-slot - - stop-network-slot - - slot_tx_end - - slot_chain_end - - Mesa genesis timestamp ---- - -# Mesa Fork Schedule - -This page collects the concrete fork-schedule values for the Mesa upgrade per network. If you are integrating with Mina (exchange, custodian, indexer, Rosetta consumer, monitoring), this is the single source of truth for **when** to act and **which release** to run. - -The relevant moments are: - -- **`stop-transaction-slot`** (a.k.a. `slot_tx_end` in the daemon config) — the slot at which nodes stop accepting new user transactions. Block production continues with empty blocks until the network-slot. See the [glossary entry](/network-upgrades/mesa/glossary#stop-transaction-slot). -- **`stop-network-slot`** (a.k.a. `slot_chain_end`) — the slot at which block production halts entirely. The network is offline between this slot and the Mesa genesis timestamp. See the [glossary entry](/network-upgrades/mesa/glossary#stop-network-slot). -- **Mesa genesis timestamp** — the wall-clock time at which the first block on the Mesa chain is produced. Exactly 3 hours after the _stop-network-slot_. See the [glossary entry](/network-upgrades/mesa/glossary#mesa-genesis-timestamp). - -## Mainnet - -:::warning Values not yet published -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` | - -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. - -## Devnet - -:::warning Values not yet published -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_ | -| `stop-transaction-slot` (`slot_tx_end`) | _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` | - -For the full preflight context, see [Preflight Network](/network-upgrades/mesa/preflight-network). - -## How to use these values - -- **Exchanges**: schedule your deposit/withdrawal freeze to begin **before** `stop-transaction-slot` and re-enable **after** the Mesa genesis timestamp confirms block production. See the [Exchanges tab on Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) for the full checklist. -- **Block producers**: install the stop-slot release any time before `stop-transaction-slot`. If you are using [automode](/network-upgrades/mesa/upgrade-modes), no further action is needed — the dispatcher will swap to the Mesa binary automatically after the Mesa release is published. -- **Archive operators**: schedule the archive schema upgrade for any time on or after `stop-network-slot`. The script is backward compatible and can also be run earlier. See [Archive Upgrade](/network-upgrades/mesa/archive-upgrade). -- **Rosetta operators**: follow the manual-mode timeline — Rosetta does not support automode. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes). diff --git a/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx index b1c395208..452f63d80 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx @@ -2,16 +2,80 @@ title: Upgrade sidebar_label: Upgrade hide_title: true -description: Upgrade phase of the Mesa hard fork — network halt, state export, and Mesa build publication. +description: Upgrade phase of the Mesa hard fork — network halt, state export, Mesa build publication, and fork schedule values per network. keywords: - Mesa - upgrade - network halt - state export + - fork schedule --- # Upgrade +## Fork Schedule + +The relevant moments that anchor the Upgrade phase: + +- **`stop-transaction-slot`** (a.k.a. `slot_tx_end`) — the slot at which nodes stop accepting new user transactions. Block production continues with empty blocks until the stop-network-slot. See [Glossary > Stop-Transaction-Slot](/network-upgrades/mesa/glossary#stop-transaction-slot). +- **`stop-network-slot`** (a.k.a. `slot_chain_end`) — the slot at which block production halts entirely. The network is offline between this slot and the Mesa genesis timestamp. See [Glossary > Stop-Network-Slot](/network-upgrades/mesa/glossary#stop-network-slot). +- **Mesa genesis timestamp** — the wall-clock time at which the first Mesa block is produced. Exactly **3 hours** after the stop-network-slot. See [Glossary > Mesa Genesis Timestamp](/network-upgrades/mesa/glossary#mesa-genesis-timestamp). + +### Mainnet + +:::warning Values not yet published +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` | + +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. + +### Devnet + +:::warning Values not yet published +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_ | +| `stop-transaction-slot` (`slot_tx_end`) | _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. + +| 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 full preflight context, see [Preflight Network](/network-upgrades/mesa/preflight-network). + +### How to use these values + +- **Exchanges**: schedule your deposit/withdrawal freeze to begin **before** `stop-transaction-slot` and re-enable **after** the Mesa genesis timestamp confirms block production. +- **Block producers**: install the stop-slot release any time before `stop-transaction-slot`. If using [automode](/network-upgrades/mesa/upgrade-modes), no further action is needed — the dispatcher swaps to the Mesa binary automatically. +- **Archive operators**: schedule the archive schema upgrade for any time on or after `stop-network-slot`. The script is backward compatible and can also be run earlier. See [Archive Upgrade](/network-upgrades/mesa/archive-upgrade). +- **Rosetta operators**: follow the manual-mode timeline — Rosetta does not support automode. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes). + +--- + Starting at the _stop-network-slot_ the network will not produce nor accept new blocks, resulting in halting the network. During the upgrade period, o1Labs will use automated tooling to export the network state based on the block at the slot just before the _stop-transaction-slot_. The exported state will then be baked into the new Mesa build, which will be used to initiate the upgraded network. It is during the upgrade window that the Mesa network infrastructure will be bootstrapped, and seed nodes will become available. o1Labs will also finalize the archive node upgrade and publish the PostgreSQL database dumps for import by the archive node operators who wish to bootstrap their archives in a trustful manner. There is a tool available to validate that the Mesa node was built from the pre-upgrade network state. 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. */} @@ -25,8 +89,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 [Validator Node docs](/node-operators/validator-node/connecting-to-the-network) for the full flag reference. ## Archive Node Operators and Rosetta Operators From 514907fb660bd463265b316efe2cc6094a550609 Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 15:26:10 +0700 Subject: [PATCH 05/12] Expand requirements.mdx with full per-actor pre-upgrade checklist --- docs/network-upgrades/mesa/requirements.mdx | 46 ++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/network-upgrades/mesa/requirements.mdx b/docs/network-upgrades/mesa/requirements.mdx index e83a6a79e..c4b2bdfba 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 is backward compatible and can be applied early. + +### 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). */} From e3ed4a7af34f9fd6d497cc877b5062950ee7dc53 Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 15:26:30 +0700 Subject: [PATCH 06/12] Add Tabs for per-network version pins in archive-upgrade.mdx --- .../network-upgrades/mesa/archive-upgrade.mdx | 39 ++++++++++++++++--- 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/docs/network-upgrades/mesa/archive-upgrade.mdx b/docs/network-upgrades/mesa/archive-upgrade.mdx index da6d57fc0..5bebfb311 100644 --- a/docs/network-upgrades/mesa/archive-upgrade.mdx +++ b/docs/network-upgrades/mesa/archive-upgrade.mdx @@ -11,6 +11,9 @@ 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. @@ -21,14 +24,38 @@ The Mesa preflight network has already forked. See [Preflight Network](/network- ::: -:::info Choosing the Mesa archive version + + -The commands below use `` as a placeholder for the archive build you want to install. Substitute the tag that matches your target network: +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. -- **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. +```bash +# Substitute this version wherever appears below +MESA_VERSION=4.0.0-preflight-3f038cb +``` -::: + + + +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. @@ -41,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 From 6b774cbc408bd30fc700ba4f5d7491c49335ae81 Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 15:27:11 +0700 Subject: [PATCH 07/12] Remove flag reference from post-upgrade.mdx; link to general validator docs instead --- docs/network-upgrades/mesa/index.mdx | 10 +++++----- .../mesa/upgrade-steps/examples.mdx | 6 +++--- .../mesa/upgrade-steps/post-upgrade.mdx | 18 ++++++++---------- .../mesa/upgrade-steps/upgrade.mdx | 2 +- 4 files changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/network-upgrades/mesa/index.mdx b/docs/network-upgrades/mesa/index.mdx index 444061682..43a26aeac 100644 --- a/docs/network-upgrades/mesa/index.mdx +++ b/docs/network-upgrades/mesa/index.mdx @@ -92,11 +92,11 @@ See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for the full compariso | 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/upgrade-steps/examples.mdx b/docs/network-upgrades/mesa/upgrade-steps/examples.mdx index 6b54d1b1d..26c8f7ef0 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/examples.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/examples.mdx @@ -57,7 +57,7 @@ The automode dispatcher only supports the `daemon` subcommand and `client status 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). @@ -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/post-upgrade.mdx b/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx index 8dfa2e37a..dd9333f88 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx @@ -288,20 +288,11 @@ 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`). @@ -418,3 +409,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/upgrade.mdx b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx index 452f63d80..907125b1c 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx @@ -90,7 +90,7 @@ 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 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 [Validator Node docs](/node-operators/validator-node/connecting-to-the-network) for the full flag reference. +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 From beebc1fb03960973c4a82b132994ff583764276e Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 15:27:30 +0700 Subject: [PATCH 08/12] Update sidebars.js: add preflight-setup, remove fork-schedule; update upgrade-steps/index description --- docs/network-upgrades/mesa/upgrade-steps/index.mdx | 2 +- sidebars.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/network-upgrades/mesa/upgrade-steps/index.mdx b/docs/network-upgrades/mesa/upgrade-steps/index.mdx index 33ac23b6f..e3340a091 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. diff --git a/sidebars.js b/sidebars.js index 16f904157..c05f139f8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -56,7 +56,6 @@ module.exports = { items: [ 'network-upgrades/mesa/requirements', 'network-upgrades/mesa/upgrade-modes', - 'network-upgrades/mesa/fork-schedule', { type: 'category', label: 'Upgrade Steps', @@ -73,6 +72,7 @@ module.exports = { }, 'network-upgrades/mesa/archive-upgrade', 'network-upgrades/mesa/preflight-network', + 'network-upgrades/mesa/preflight-setup', 'network-upgrades/mesa/troubleshooting', { type: 'category', From 29029da5da1aac9faaa848baa5e0b0ce86f3b645 Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 19:22:45 +0700 Subject: [PATCH 09/12] Add redirects for deleted fork-schedule.mdx -> upgrade-steps/upgrade --- docusaurus.config.js | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docusaurus.config.js b/docusaurus.config.js index efd128337..74d57c728 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/upgrade-steps/upgrade', + }, { from: '/mesa-upgrade/flags-configs', to: '/network-upgrades/mesa/upgrade-steps/post-upgrade', @@ -352,6 +356,10 @@ module.exports = { from: '/network-upgrades/mesa/appendix', to: '/network-upgrades/mesa/appendix/archive-node-schema-changes', }, + { + from: '/network-upgrades/mesa/fork-schedule', + to: '/network-upgrades/mesa/upgrade-steps/upgrade', + }, { from: '/network-upgrades/mesa/upgrade-modes-details', to: '/network-upgrades/mesa/appendix/upgrade-modes-details', From e0ef5d5ba4a0778ed8814d7e23613794a66e796f Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 19:48:47 +0700 Subject: [PATCH 10/12] Deduplicate internal/repeated content with cross-links: dispatcher limitation, manual mode, exchange danger-box, backward-compatible phrasing. Add links from Mesa flag ref to external snark-workers/rosetta docs. --- docs/network-upgrades/mesa/index.mdx | 2 +- docs/network-upgrades/mesa/requirements.mdx | 2 +- docs/network-upgrades/mesa/upgrade-steps/examples.mdx | 4 ++-- docs/network-upgrades/mesa/upgrade-steps/index.mdx | 2 +- docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx | 6 ++++++ .../mesa/upgrade-steps/state-finalization.mdx | 2 +- docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx | 2 +- 7 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/network-upgrades/mesa/index.mdx b/docs/network-upgrades/mesa/index.mdx index 43a26aeac..f91d49025 100644 --- a/docs/network-upgrades/mesa/index.mdx +++ b/docs/network-upgrades/mesa/index.mdx @@ -30,7 +30,7 @@ Mesa bundles four Mina Improvement Proposals (MIPs) that change protocol behavio ### 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 diff --git a/docs/network-upgrades/mesa/requirements.mdx b/docs/network-upgrades/mesa/requirements.mdx index c4b2bdfba..48d9aa4d6 100644 --- a/docs/network-upgrades/mesa/requirements.mdx +++ b/docs/network-upgrades/mesa/requirements.mdx @@ -77,7 +77,7 @@ Before the fork, each actor type must complete specific preparations. Complete t - 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 is backward compatible and can be applied early. +- 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 diff --git a/docs/network-upgrades/mesa/upgrade-steps/examples.mdx b/docs/network-upgrades/mesa/upgrade-steps/examples.mdx index 26c8f7ef0..578db0c53 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/examples.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/examples.mdx @@ -52,7 +52,7 @@ 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. @@ -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: diff --git a/docs/network-upgrades/mesa/upgrade-steps/index.mdx b/docs/network-upgrades/mesa/upgrade-steps/index.mdx index e3340a091..3f7f33fcb 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/index.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/index.mdx @@ -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 dd9333f88..aca7e09ee 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx @@ -119,6 +119,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' \ @@ -322,6 +324,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 @@ -343,6 +347,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 diff --git a/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx b/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx index 4efd5d1b1..41576ebbc 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx @@ -36,7 +36,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 907125b1c..059b8cc5b 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx @@ -71,7 +71,7 @@ For full preflight context, see [Preflight Network](/network-upgrades/mesa/prefl - **Exchanges**: schedule your deposit/withdrawal freeze to begin **before** `stop-transaction-slot` and re-enable **after** the Mesa genesis timestamp confirms block production. - **Block producers**: install the stop-slot release any time before `stop-transaction-slot`. If using [automode](/network-upgrades/mesa/upgrade-modes), no further action is needed — the dispatcher swaps to the Mesa binary automatically. -- **Archive operators**: schedule the archive schema upgrade for any time on or after `stop-network-slot`. The script is backward compatible and can also be run earlier. See [Archive Upgrade](/network-upgrades/mesa/archive-upgrade). +- **Archive operators**: schedule the archive schema upgrade for any time on or after `stop-network-slot`. The [Archive Upgrade](/network-upgrades/mesa/archive-upgrade) script can also be run earlier. - **Rosetta operators**: follow the manual-mode timeline — Rosetta does not support automode. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes). --- From 488256b27437c268dba33ff21bad3654c06d4c29 Mon Sep 17 00:00:00 2001 From: glyh Date: Tue, 14 Jul 2026 15:52:45 +0700 Subject: [PATCH 11/12] Address Mesa review feedback --- docs/network-upgrades/mesa/fork-schedule.mdx | 77 ++++++++++++++++++ docs/network-upgrades/mesa/glossary.mdx | 1 + docs/network-upgrades/mesa/index.mdx | 2 +- .../mesa/upgrade-steps/post-upgrade.mdx | 26 ++++++- .../mesa/upgrade-steps/state-finalization.mdx | 11 +++ .../mesa/upgrade-steps/upgrade.mdx | 78 ++++--------------- docusaurus.config.js | 7 +- sidebars.js | 1 + src/theme/Admonition/index.tsx | 2 +- 9 files changed, 132 insertions(+), 73 deletions(-) create mode 100644 docs/network-upgrades/mesa/fork-schedule.mdx diff --git a/docs/network-upgrades/mesa/fork-schedule.mdx b/docs/network-upgrades/mesa/fork-schedule.mdx new file mode 100644 index 000000000..3b40133a2 --- /dev/null +++ b/docs/network-upgrades/mesa/fork-schedule.mdx @@ -0,0 +1,77 @@ +--- +title: Mesa Fork Schedule +sidebar_label: Fork Schedule +hide_title: true +description: Concrete fork-schedule values for the Mesa upgrade — Mesa genesis timestamp, stop-transaction-slot (slot_tx_end), stop-network-slot (slot_chain_end), and pre-fork / Mesa release versions per network. +keywords: + - Mesa + - fork schedule + - stop-transaction-slot + - stop-network-slot + - slot_tx_end + - slot_chain_end + - Mesa genesis timestamp +--- + +# Mesa Fork Schedule + +This page collects the concrete fork-schedule values for the Mesa upgrade per network. If you are integrating with Mina (exchange, custodian, indexer, Rosetta consumer, monitoring), this is the single source of truth for **when** to act and **which release** to run. + +The relevant moments are: + +- **`stop-transaction-slot`** (a.k.a. `slot_tx_end` in the daemon config) — the slot at which nodes stop accepting new user transactions. Block production continues with empty blocks until the network-slot. See the [glossary entry](/network-upgrades/mesa/glossary#stop-transaction-slot). +- **`stop-network-slot`** (a.k.a. `slot_chain_end`) — the slot at which block production halts entirely. The network is offline between this slot and the Mesa genesis timestamp. See the [glossary entry](/network-upgrades/mesa/glossary#stop-network-slot). +- **Mesa genesis timestamp** — the wall-clock time at which the first block on the Mesa chain is produced. Exactly 3 hours after the _stop-network-slot_. See the [glossary entry](/network-upgrades/mesa/glossary#mesa-genesis-timestamp). + +## Mainnet + +:::warning Values not yet published +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` | + +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. + +## Devnet + +:::warning Values not yet published +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_ | +| `stop-transaction-slot` (`slot_tx_end`) | _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` | + +For the full preflight context, see [Preflight Network](/network-upgrades/mesa/preflight-network). + +## How to use these values + +- **Exchanges**: schedule your deposit/withdrawal freeze to begin **before** `stop-transaction-slot` and re-enable **after** the Mesa genesis timestamp confirms block production. See the [Exchanges tab on Post-Upgrade](/network-upgrades/mesa/upgrade-steps/post-upgrade) for the full checklist. +- **Block producers**: install the stop-slot release any time before `stop-transaction-slot`. If you are using [automode](/network-upgrades/mesa/upgrade-modes), no further action is needed — the dispatcher will swap to the Mesa binary automatically after the Mesa release is published. +- **Archive operators**: schedule the archive schema upgrade for any time on or after `stop-network-slot`. The script is backward compatible and can also be run earlier. See [Archive Upgrade](/network-upgrades/mesa/archive-upgrade). +- **Rosetta operators**: follow the manual-mode timeline — Rosetta does not support automode. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes). diff --git a/docs/network-upgrades/mesa/glossary.mdx b/docs/network-upgrades/mesa/glossary.mdx index 222ffbd13..3b296af79 100644 --- a/docs/network-upgrades/mesa/glossary.mdx +++ b/docs/network-upgrades/mesa/glossary.mdx @@ -130,6 +130,7 @@ 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. +- **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. ### Expanded zkApp State — [MIP7](https://github.com/MinaProtocol/MIPs/blob/main/MIPS/mip-0007-increase-state-size-limit.md) diff --git a/docs/network-upgrades/mesa/index.mdx b/docs/network-upgrades/mesa/index.mdx index f91d49025..935010499 100644 --- a/docs/network-upgrades/mesa/index.mdx +++ b/docs/network-upgrades/mesa/index.mdx @@ -70,7 +70,7 @@ At the predefined **stop-transaction-slot**, nodes stop accepting new user trans > **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, and publishes packages. See **[Upgrade](/network-upgrades/mesa/upgrade-steps/upgrade)** for the full per-actor instructions and fork schedule. +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 diff --git a/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx b/docs/network-upgrades/mesa/upgrade-steps/post-upgrade.mdx index aca7e09ee..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 @@ -152,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 @@ -167,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. @@ -182,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 \ @@ -190,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 \ @@ -203,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 \ @@ -211,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; ``` @@ -297,9 +320,10 @@ The flags below are **unchanged from Berkeley** — if your node was running cor 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 diff --git a/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx b/docs/network-upgrades/mesa/upgrade-steps/state-finalization.mdx index 41576ebbc..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. diff --git a/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx index 059b8cc5b..cb6881052 100644 --- a/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx +++ b/docs/network-upgrades/mesa/upgrade-steps/upgrade.mdx @@ -2,84 +2,32 @@ title: Upgrade sidebar_label: Upgrade hide_title: true -description: Upgrade phase of the Mesa hard fork — network halt, state export, Mesa build publication, and fork schedule values per network. +description: Upgrade phase of the Mesa hard fork — network halt, state export, and Mesa build publication. keywords: - Mesa - upgrade - network halt - state export - - fork schedule --- # Upgrade -## Fork Schedule - -The relevant moments that anchor the Upgrade phase: - -- **`stop-transaction-slot`** (a.k.a. `slot_tx_end`) — the slot at which nodes stop accepting new user transactions. Block production continues with empty blocks until the stop-network-slot. See [Glossary > Stop-Transaction-Slot](/network-upgrades/mesa/glossary#stop-transaction-slot). -- **`stop-network-slot`** (a.k.a. `slot_chain_end`) — the slot at which block production halts entirely. The network is offline between this slot and the Mesa genesis timestamp. See [Glossary > Stop-Network-Slot](/network-upgrades/mesa/glossary#stop-network-slot). -- **Mesa genesis timestamp** — the wall-clock time at which the first Mesa block is produced. Exactly **3 hours** after the stop-network-slot. See [Glossary > Mesa Genesis Timestamp](/network-upgrades/mesa/glossary#mesa-genesis-timestamp). - -### Mainnet - -:::warning Values not yet published -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` | - -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. - -### Devnet - -:::warning Values not yet published -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_ | -| `stop-transaction-slot` (`slot_tx_end`) | _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. - -| 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 full preflight context, see [Preflight Network](/network-upgrades/mesa/preflight-network). - -### How to use these values - -- **Exchanges**: schedule your deposit/withdrawal freeze to begin **before** `stop-transaction-slot` and re-enable **after** the Mesa genesis timestamp confirms block production. -- **Block producers**: install the stop-slot release any time before `stop-transaction-slot`. If using [automode](/network-upgrades/mesa/upgrade-modes), no further action is needed — the dispatcher swaps to the Mesa binary automatically. -- **Archive operators**: schedule the archive schema upgrade for any time on or after `stop-network-slot`. The [Archive Upgrade](/network-upgrades/mesa/archive-upgrade) script can also be run earlier. -- **Rosetta operators**: follow the manual-mode timeline — Rosetta does not support automode. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes). - ---- - Starting at the _stop-network-slot_ the network will not produce nor accept new blocks, resulting in halting the network. During the upgrade period, o1Labs will use automated tooling to export the network state based on the block at the slot just before the _stop-transaction-slot_. The exported state will then be baked into the new Mesa build, which will be used to initiate the upgraded network. It is during the upgrade window that the Mesa network infrastructure will be bootstrapped, and seed nodes will become available. o1Labs will also finalize the archive node upgrade and publish the PostgreSQL database dumps for import by the archive node operators who wish to bootstrap their archives in a trustful manner. There is a tool available to validate that the Mesa node was built from the pre-upgrade network state. 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 diff --git a/docusaurus.config.js b/docusaurus.config.js index 74d57c728..03736aa51 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -342,7 +342,7 @@ module.exports = { }, { from: '/mesa-upgrade/fork-schedule', - to: '/network-upgrades/mesa/upgrade-steps/upgrade', + to: '/network-upgrades/mesa/fork-schedule', }, { from: '/mesa-upgrade/flags-configs', @@ -356,10 +356,7 @@ module.exports = { from: '/network-upgrades/mesa/appendix', to: '/network-upgrades/mesa/appendix/archive-node-schema-changes', }, - { - from: '/network-upgrades/mesa/fork-schedule', - to: '/network-upgrades/mesa/upgrade-steps/upgrade', - }, + // 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 c05f139f8..c431c6f8b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -56,6 +56,7 @@ module.exports = { items: [ 'network-upgrades/mesa/requirements', 'network-upgrades/mesa/upgrade-modes', + 'network-upgrades/mesa/fork-schedule', { type: 'category', label: 'Upgrade Steps', 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; From 2d5352471144d6b8fe315843610730a8daa67da7 Mon Sep 17 00:00:00 2001 From: glyh Date: Wed, 1 Jul 2026 19:51:40 +0700 Subject: [PATCH 12/12] regenerate llm-full.txt --- static/llms-full.txt | 574 ++++++++++++++++++++++--------------------- 1 file changed, 293 insertions(+), 281 deletions(-) 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