added initial draft for upgrade to mesa

docs/network-upgrades/berkeley/index.mdx

@@ -0,0 +1,41 @@
+---
+title: Berkeley Upgrade
+sidebar_label: Berkeley Upgrade
+hide_title: true
+description: Overview of the Berkeley network upgrade for Mina Protocol — the transition to the Berkeley proof system with zkApp support.
+keywords:
+  - Berkeley
+  - upgrade
+  - hard fork
+  - zkApps
+---
+
+# Berkeley Upgrade
+
+The Berkeley upgrade was the most significant network upgrade in Mina's history, transitioning mainnet from the legacy proof system to the Berkeley proof system. It was completed in June 2024.
+
+## What Berkeley Introduced
+
+### zkApp Programmability
+
+Berkeley brought full zkApp (zero-knowledge application) support to mainnet. Developers can deploy smart contracts that execute off-chain computation and generate zero-knowledge proofs verified on-chain, enabling privacy-preserving applications with minimal on-chain footprint.
+
+### Recursive Proofs
+
+The upgrade enabled recursive proof composition, allowing proofs to verify other proofs. This is foundational to Mina's constant-size blockchain — the entire chain state can be verified with a single proof regardless of history length.
+
+### New Transaction Model
+
+Berkeley introduced a new transaction format supporting zkApp commands alongside traditional payment and delegation transactions. This included on-chain state storage for smart contracts, events, and actions.
+
+### Archive Database Migration
+
+The upgrade required a full archive database migration from the legacy schema to the Berkeley schema. This was the most operationally intensive part of the upgrade for archive node operators, taking up to 48 hours for the trustless migration path.
+
+## Upgrade Details
+
+- **Release**: [3.0.0](https://github.com/MinaProtocol/mina/releases/tag/3.0.0) (Berkeley mainnet release)
+- **Upgrade mode**: Manual only (automode was not available for Berkeley)
+- **Archive migration**: Trustless (48h) or trustful (o1Labs database export)
+
+For the operational details of the Berkeley upgrade, see the sub-pages below. These are preserved for historical reference.

docs/network-upgrades/index.mdx

@@ -1,18 +1,19 @@
 ---
 title: Network Upgrades
 sidebar_label: Network Upgrades
-description: History of Mina protocol network upgrades on mainnet.
+hide_title: true
+description: History of Mina Protocol mainnet network upgrades (hard forks), including Berkeley and Mesa.
 keywords:
-  - mina network upgrades
-  - berkeley upgrade
-  - mesa upgrade
+  - Mina
+  - network upgrade
   - hard fork
-  - protocol upgrade
+  - Berkeley
+  - Mesa
 ---
 
 # Network Upgrades
 
-Mina protocol evolves through network upgrades (hard forks) that introduce new features and improvements. Each upgrade requires node operators to update their software to remain compatible with the network.
+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
 

docs/network-upgrades/mesa/appendix.mdx

@@ -0,0 +1,67 @@
+---
+title: Archive Node Schema Changes
+sidebar_label: Archive Node Schema Changes
+hide_title: true
+description: Reference of database schema changes applied to the Mina archive node during the Mesa hard fork — new columns, modified tables, and the SQL applied by the upgrade script.
+keywords:
+  - Mesa
+  - upgrade
+  - appendix
+  - archive
+  - schema
+  - database
+---
+
+# Archive Node Schema Changes
+
+## Upgrading archive nodes from Berkeley to Mesa
+
+Below we present details of what changed in the archive node database schema between Berkeley and Mesa versions.
+
+### Extended zkApp State Fields
+
+Both zkApp state tables have been modified to support additional state elements:
+
+**zkapp_states_nullable table**
+   - Added columns `element8` through `element31` (nullable integer fields)
+   - Each new column references `zkapp_field(id)`
+   - These fields allow zkApps to store additional state information beyond the original 8 elements
+
+```sql
+ALTER TABLE zkapp_states_nullable ADD COLUMN IF NOT EXISTS element8 INT REFERENCES zkapp_field(id);
+...
+ALTER TABLE zkapp_states_nullable ADD COLUMN IF NOT EXISTS element31 INT REFERENCES zkapp_field(id);
+```
+
+**zkapp_states table**
+   - Added columns `element8` through `element31` (non-nullable integer fields)
+   - Each new column references `zkapp_field(id)` with a default value pointing to the zero field
+   - Unlike the nullable version, these fields are required and default to the zero field ID
+
+```sql
+ALTER TABLE zkapp_states ADD COLUMN IF NOT EXISTS element8 INT DEFAULT <zero_field_id> NOT NULL REFERENCES zkapp_field(id);
+...
+ALTER TABLE zkapp_states ADD COLUMN IF NOT EXISTS element31 INT DEFAULT <zero_field_id> NOT NULL REFERENCES zkapp_field(id);
+```
+
+This expansion allows zkApps to store up to 32 state elements instead of the previous 8, significantly increasing the state storage capacity for complex smart contracts.
+
+### Version Tracking
+
+The upgrade introduces a new `version` table to keep track of the database schema version. The purpose of this table is to help with future database migrations. The table tracks which migration scripts were applied and when.
+
+**version table**
+```sql
+CREATE TABLE IF NOT EXISTS version (
+    version_num INT PRIMARY KEY,
+    applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+The version table provides:
+- **Migration tracking**: Records which migrations have been applied
+- **Timestamp tracking**: Shows when each migration was executed
+- **Idempotency**: Prevents duplicate migration runs
+- **Version identification**: Easily identify the current database schema version
+
+The table is created if it does not exist already. Rollback and upgrade scripts will insert a new row with the version number and timestamp when the script was applied.

docs/network-upgrades/mesa/archive-upgrade.mdx

@@ -34,7 +34,7 @@ The commands below use `<MESA_VERSION>` as a placeholder for the archive build y
 
 To successfully upgrade the archive database to Mesa, you must ensure that your environment meets the foundational requirements.
 
-## Migration host
+## Upgrade host
 
 - PostgreSQL database for database server
 - If you use Docker, then any of the supported OS by Mina (bullseye, focal, noble, bookworm or jammy) with at least 32 GB of RAM
@@ -106,7 +106,7 @@ Make sure to replace `<username>` and `<database>` with your actual PostgreSQL u
 #### Rollback
 
 You can rollback the upgrade process by restoring the database from a backup taken before running the upgrade script.
-Another is to run rollback script which is part of the upgrade script. It will drop all tables and other database objects created by the upgrade script.
+Another alternative is to run the rollback script, which is part of the upgrade script. It will drop all tables and other database objects created by the upgrade script.
 It will also update the version table to reflect the rollback.
 
 ##### Running the rollback script
@@ -125,54 +125,112 @@ Make sure to replace `<username>` and `<database>` with your actual PostgreSQL u
 After successfully running the upgrade script, you DO NOT need to restart your archive node or Rosetta API.
 Changes in upgrade script are backward compatible and will be picked up by the archive node and Rosetta API automatically.
 
-### Verification
-To verify that the upgrade was successful, you can check the version table in the PostgreSQL database.
+### Verification with the Archive Hardfork Toolbox
 
-You can do this by running the following command:
+The `mina-archive-hardfork-toolbox` is a dedicated CLI tool for verifying the integrity of archive database upgrades and fork transitions. It is shipped with the Mina archive package and available as a standalone binary.
+
+For full details, see the [toolbox README](https://github.com/MinaProtocol/mina/blob/compatible/src/app/archive_hardfork_toolbox/README.md).
+
+All commands below require a `--postgres-uri` flag in the format:
+```
+postgresql://<user>:<password>@<host>:<port>/<database>
+```
+
+#### Step 1: Pre-fork validation (before the fork)
+
+Verify the fork block candidate is valid before the network halts.
+
+**Check that the fork block is in the best chain:**
 ```bash
-psql -U <username> -d <database> -c "SELECT * FROM version;"
+mina-archive-hardfork-toolbox fork-candidate is-in-best-chain \
+  --postgres-uri <uri> \
+  --fork-state-hash <hash> \
+  --fork-height <height> \
+  --fork-slot <slot>
 ```
-Make sure to replace `<username>` and `<database>` with your actual PostgreSQL username and database name.
 
-If the upgrade was successful, you should see the new version number in the output.
+**Verify the fork block has enough confirmations:**
+```bash
+mina-archive-hardfork-toolbox fork-candidate confirmations \
+  --postgres-uri <uri> \
+  --latest-state-hash <hash> \
+  --fork-slot <slot> \
+  --required-confirmations <n>
+```
 
-We put a lot of effort into making the upgrade process as smooth as possible.
-However, if you encounter any issues or need assistance, please reach out to the Mina community on [Discord](https://discord.gg/minaprotocol) or [GitHub Discussions](https://github.com/MinaProtocol/mina/discussions).
+**Verify no commands were executed after the fork block** (ensures a clean fork point):
+```bash
+mina-archive-hardfork-toolbox fork-candidate no-commands-after \
+  --postgres-uri <uri> \
+  --fork-state-hash <hash> \
+  --fork-slot <slot>
+```
 
-## Appendix: Database Schema Changes
+**Find the last block with transactions** (useful for identifying the fork point):
+```bash
+mina-archive-hardfork-toolbox fork-candidate last-filled-block \
+  --postgres-uri <uri>
+```
 
-Below we present details of what was changed in the archive node database schema between Berkeley and Mesa versions.
+#### Step 2: Verify the schema upgrade
 
-### Zkapp_state_nullable Additional Columns
+After running `upgrade-to-mesa.sql`, verify the database schema was upgraded correctly:
 
-The `zkapp_state_nullable` table has been modified to include new columns `element8` through `element31` which are nullable and can store additional state information for zkApps.
+```bash
+mina-archive-hardfork-toolbox verify-upgrade \
+  --postgres-uri <uri> \
+  --protocol-version <version> \
+  --migration-version <version>
+```
 
-```sql
-, element8          int     REFERENCES zkapp_field(id)
-...
-, element31         int     REFERENCES zkapp_field(id)
-);
+You can also verify manually by checking the version table:
+```bash
+psql -U <username> -d <database> -c "SELECT * FROM version;"
 ```
 
-This expansion allows zkApps to store up to 31 state elements instead of the previous 8, significantly increasing the state storage capacity for complex smart contracts.
+If the upgrade was successful, the version table will contain an entry with the expected version number and a recent timestamp.
+
+#### Step 3: Post-fork validation
+
+After the fork activates and the Mesa chain is running, validate the fork block and its ancestry:
 
-### Version Table
+```bash
+mina-archive-hardfork-toolbox validate-fork \
+  --postgres-uri <uri> \
+  --fork-state-hash <hash> \
+  --fork-slot <slot>
+```
 
-We also introduced a new table `version` to keep track of the database schema version.
-The purpose of this table is to help with future database migrations. The table tracks which migration scripts were applied and when.
-Ultimately it helps to determine the current version of the database schema and helps to avoid applying the same migration script multiple times.
+#### Step 4: Mark the canonical chain (if needed)
 
-This table is created if it does not exist already. Rollback and upgrade scripts will insert a new row with the version number and timestamp when the script was applied.
+If you need to mark the chain leading to a specific block as canonical for the new protocol version:
 
-```sql
-CREATE TABLE IF NOT EXISTS version (
-    version_num INT PRIMARY KEY,
-    applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
-);
+```bash
+mina-archive-hardfork-toolbox convert-chain-to-canonical \
+  --postgres-uri <uri> \
+  --target-block-hash <state-hash> \
+  --protocol-version <transaction>.<network>.<patch>
 ```
 
-The version table provides:
-- **Migration tracking**: Records which migrations have been applied
-- **Timestamp tracking**: Shows when each migration was executed
-- **Idempotency**: Prevents duplicate migration runs
-- **Version identification**: Easily identify the current database schema version
+Optionally use `--stop-at-slot <slot>` to limit how far back in history the marking goes.
+
+:::tip Typical workflow
+1. **Before the fork**: run `fork-candidate` commands to validate the fork block
+2. **After running the upgrade script**: run `verify-upgrade` to confirm the schema upgrade
+3. **After the fork activates**: run `validate-fork` to confirm data integrity
+4. **For full archive verification**: run the [Archive Replayer](/network-upgrades/mesa/replayer) to replay all transactions and compare the resulting ledger against the official fork config
+:::
+
+If you encounter any issues, reach out to the Mina community on [Discord](https://discord.gg/minaprotocol) or [GitHub Discussions](https://github.com/MinaProtocol/mina/discussions).
+
+## Full Archive Verification with the Replayer
+
+The toolbox commands above verify the schema and fork block integrity, but they do not verify every transaction in the archive. For complete end-to-end verification, use the **[Archive Replayer](/network-upgrades/mesa/replayer)** — a tool that replays all transactions from genesis (or a checkpoint) through the fork point, recomputing the ledger state and comparing it against the official fork config.
+
+The replayer is not limited to upgrade-time use. It is an **ongoing verification tool** that can be run at any time to confirm your archive database faithfully represents the canonical chain. After the Mesa upgrade, you can continue running it against Mesa blocks to detect any data corruption or missing blocks.
+
+See [Archive Replayer](/network-upgrades/mesa/replayer) for usage, flags, and examples.
+
+## Database Schema Changes
+
+For the full schema diff (new columns, modified tables, applied SQL), see [Archive Node Schema Changes](/network-upgrades/mesa/appendix).

docs/network-upgrades/mesa/docker-compose-quickstart.mdx

@@ -0,0 +1,65 @@
+---
+title: Docker Compose Quickstart
+sidebar_label: Docker Compose Quickstart
+hide_title: true
+description: Run a Mina node with automode enabled for the Mesa upgrade using Docker Compose.
+keywords:
+  - Mesa
+  - Docker Compose
+  - automode
+  - quickstart
+---
+
+# Docker Compose Quickstart
+
+```yaml
+services:
+  mina_node:
+    image: 'minaprotocol/mina-daemon-auto-hardfork:<version>-noble-mainnet'
+    restart: always
+    environment:
+      MINA_CLIENT_TRUSTLIST: "0.0.0.0/0"
+    entrypoint: []
+    command: >
+      bash -c '
+        mina daemon \
+             --peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt \
+             --insecure-rest-server \
+             --rest-port 3085 \
+             --hardfork-handling migrate-exit
+      '
+    volumes:
+      - './mina-config:/root/.mina-config'
+    ports:
+      - '3085:3085'
+      - '8302:8302'
+```
+
+Replace `<version>` with the published stop-slot release from the [Mina releases page](https://github.com/MinaProtocol/mina/releases).
+
+:::tip Docker image tag
+Use the stop-slot release image for your target network. For devnet, replace the image tag suffix `mainnet` with `devnet` and use the corresponding devnet release tag.
+:::
+
+:::tip Peer list URL
+The `--peer-list-url` above points to the mainnet bootnodes. For devnet, replace it with `https://bootnodes.minaprotocol.com/networks/devnet.txt`.
+:::
+
+:::tip Additional environment variables
+Add any extra configuration (e.g. `MINA_PRIVKEY_PASS`) under the `environment` section.
+:::
+
+## Switching back to normal Docker
+
+After your node has completed the Mesa transition and you want to move off `mina-daemon-auto-hardfork`, update your Compose config as follows:
+
+- Remove `--hardfork-handling migrate-exit`.
+- Set the Docker image to the post-fork artifact, for example `minaprotocol/mina-daemon:<mesa-version>-noble-mainnet`.
+
+```bash
+docker compose up -d
+```
+
+:::caution
+`restart: always` and the persistent `mina-config` volume are required for automode. If the volume is wiped between restarts, the node cannot transition to Mesa. See [Upgrade Modes](/network-upgrades/mesa/upgrade-modes) for details.
+:::