added initial draft for upgrade to mesa

docs/mesa-upgrade/appendix.mdx

@@ -0,0 +1,69 @@
+---
+title: Appendix
+sidebar_label: Appendix
+hide_title: true
+description: Mesa Upgrade Appendix
+keywords:
+  - Mesa
+  - upgrade
+  - appendix
+---
+
+# Appendix
+
+## 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
+
+**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);
+```
+
+### Migration History Tracking
+
+The upgrade introduces a new `migration_history` table to track database schema migrations. This helps manage future upgrades and prevents applying the same migration multiple times.
+
+**migration_status enum type**
+```sql
+CREATE TYPE migration_status AS ENUM ('starting', 'applied', 'failed');
+```
+
+**migration_history table**
+```sql
+CREATE TABLE IF NOT EXISTS migration_history (
+    commit_start_at   TIMESTAMPTZ NOT NULL DEFAULT NOW() PRIMARY KEY,
+    protocol_version  TEXT NOT NULL,
+    migration_version TEXT NOT NULL,
+    description       TEXT NOT NULL,
+    status            migration_status NOT NULL
+);
+```
+
+The table tracks:
+- **commit_start_at**: Timestamp when the migration started
+- **protocol_version**: Target protocol version (e.g., '4.0.0' for Mesa)
+- **migration_version**: Version of the migration script itself (e.g., '0.0.5')
+- **description**: Human-readable description of the migration
+- **status**: Current state of the migration (starting, applied, or failed)
+
+The migration script uses protocol version '3.0.0' for Berkeley and '4.0.0' for Mesa, with built-in safety checks to prevent reapplying migrations or running them on incorrect database versions.

docs/mesa-upgrade/flags-configs.mdx

@@ -0,0 +1,137 @@
+---
+title: Post-Upgrade Flags and Configurations for Mainnet
+sidebar_label: Post-Upgrade Flags and Configurations
+hide_title: true
+description: Post-Upgrade Flags and Configurations for Mainnet
+keywords:
+  - Berkeley
+  - upgrade
+  - flags
+  - configurations
+---
+
+# Post-Upgrade Flags and Configurations for Mainnet
+
+Please refer to the Berkeley node release notes [here](https://github.com/MinaProtocol/mina/releases/tag/3.0.3).
+
+### Network details
+
+```
+Chain ID
+a7351abc7ddf2ea92d1b38cc8e636c271c1dfd2c081c637f62ebc2af34eb7cc1
+
+Git SHA-1
+ae112d3a96fe71b4ccccf3c54e7b7494db4898a4
+
+Seed List
+https://bootnodes.minaprotocol.com/networks/mainnet.txt
+
+Node build
+https://github.com/MinaProtocol/mina/releases/tag/3.0.3
+```
+
+### Block Producer's
+
+Start your node post-upgrade in Mainnet with the flags and environment variables listed below.
+
+```
+mina daemon
+--block-producer-key <path to the wallet private key file>
+--config-directory <path to the mina configuration directory>
+--file-log-rotations 500
+--generate-genesis-proof true
+--libp2p-keypair <keyfile path>
+--log-json
+--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt
+
+ENVIRONMENT VARIABLES
+RAYON_NUM_THREADS=6
+MINA_LIBP2P_PASS
+MINA_PRIVKEY_PASS
+```
+
+### SNARK Coordinator
+Configure your node post-upgrade in Mainnet with specific flags and environment variables as listed.
+
+```
+mina daemon
+--config-directory <path to the mina configuration directory>
+--enable-peer-exchange true
+--file-log-rotations 500
+--libp2p-keypair <keyfile path>
+--log-json
+--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt
+--run-snark-coordinator <public key>
+--snark-worker-fee 0.001
+--work-selection [seq|rand|roffset]
+
+ENVIRONMENT VARIABLES
+MINA_LIBP2P_PASS
+```
+
+### SNARK Workers
+Connect to a SNARK Coordinator node if required and run the following flags.
+```
+mina internal snark-worker
+--proof-level full
+--shutdown-on-disconnect false
+--daemon-address <snark coordinator IP:port>
+
+ENVIRONMENT VARIABLES
+RAYON_NUM_THREADS:8
+```
+
+### Archive Node
+Running an Archive Node involves setting up a non-block-producing node and a PostgreSQL database configured with specific flags and environment variables.
+
+For more information about running archive nodes, see [Archive Node](/node-operators/archive-node).
+
+The PostgreSQL database requires two schemas:
+1. The PostgreSQL schema used by the Mina archive database: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.3)
+2. The PostgreSQL schema extensions to support zkApp commands: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.3)
+
+The non-block-producing node must be configured with the following flags:
+```
+mina daemon
+--archive-address <archive_address>:<archive_port - use 3086>
+--config-directory <path to mina config>
+--enable-peer-exchange true
+--file-log-rotations 500
+--generate-genesis-proof true
+--libp2p-keypair <keyfile path>
+--log-json
+--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt
+
+ENVIRONMENT VARIABLES
+MINA_LIBP2P_PASS
+```
+
+This non-block-producing node connects to the archive node with the addresses and port specified in the `--archive-address` flag.
+
+The **archive node** command looks like this:
+
+```
+mina-archive run
+--metrics-port <port>
+--postgres-uri postgres://<user>:<password>@<address>:<port>/<db>
+--server-port 3086
+--log-json
+--log-level DEBUG
+```
+
+### Rosetta API
+Once you have the Archive Node stack up and running, start the Rosetta API Docker image with the following command:
+
+```
+docker run
+--name rosetta --rm \
+-p 3088:3088 \
+--entrypoint '' \
+minaprotocol/mina-rosetta:3.1.0-ae112d3-bullseye-mainnet \
+/usr/local/bin/mina-rosetta \
+--archive-uri "${PG_CONNECTION_STRING}" \
+--graphql-uri "${GRAPHQL_URL}" \
+--log-json \
+--log-level ${LOG_LEVEL} \
+--port 3088
+```

docs/mesa-upgrade/requirements.mdx

@@ -0,0 +1,67 @@
+---
+title: Requirements
+sidebar_label: Requirements
+hide_title: true
+description: Berkeley upgrade is a major upgrade that requires all nodes in a network to upgrade to a newer version. It is not backward compatible.
+keywords:
+  - Berkeley
+  - upgrade
+  - hardware requirements
+---
+
+# Requirements
+
+## Hardware Requirements
+
+Please note the following are the hardware requirements for each node type after the upgrade:
+
+| Node Type | Memory | CPU | Storage | Network |
+|--|--|--|--|--|
+| Mina Daemon Node | 32 GB RAM | 8 core processor with BMI2 and AVX CPU instruction set are required | 64 GB | 1 Mbps Internet Connection |
+| SNARK Coordinator | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection |
+| SNARK Worker | 32 GB RAM | 4 core/8 threads per worker with BMI2 and AVX CPU instruction set are required | 64 GB | 1 Mbps Internet Connection |
+| Archive Node | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection |
+| Rosetta API standalone Docker image | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection |
+| Mina Seed Node | 64 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection |
+
+## Mina Daemon Requirements
+
+### Installation
+
+:::caution
+
+If you have `mina-generate-keypair` installed, you will need to first `sudo apt remove mina-generate-keypair` before installing `mina-mainnet=3.1.0-ae112d3`.
+The `mina-generate-keypair` binary is now installed as part of the mina-mainnet package.
+
+:::
+
+### IP and Port configuration
+
+**IP:**
+
+By default, the Mina Daemon will attempt to retrieve its public IP address from the system. If you are running the node behind a NAT or firewall, you can set the `--external-ip` flag to specify the public IP address.
+
+**Port:**
+
+Nodes must expose a port publicly to communicate with other peers.
+Mina uses by default the port `8302` which is the default libp2p port.
+
+You can use a different port by setting the `--external-port` flag.
+
+### Node Auto-restart
+
+Ensure your nodes are set to restart automatically after a crash. For guidance, refer to the [auto-restart instructions](/node-operators/block-producer-node/connecting-to-the-network#start-a-mina-node-with-auto-restart-flows-using-systemd)
+
+## Seed Peer Requirements
+
+### Generation of libp2p keypair
+
+To ensure connectivity across the network, it is essential that all seed nodes start with the **same** `libp2p` keypair.
+This consistency allows other nodes in the network to reliably connect.
+Although the same libp2p keys can be reused from before the upgrade, if you need to manually generate new libp2p keys, use the following command:
+
+```
+mina libp2p generate-keypair --privkey-path <path-to-the-key-file>
+```
+
+Further information on [generating key pairs](/node-operators/generating-a-keypair) on Mina Protocol.