added initial draft for upgrade to mesa

docs/mesa-upgrade/appendix.mdx

@@ -0,0 +1,42 @@
+---
+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 presents details what was changed in the archive node database schema between Berkeley and Mesa version.
+
+**Zkapp_state_nullable additional Columns **
+   - The `zkapp_state_nullable` table has been modified to include a new columns `element8` to `element31` which are nullable and can store additional state information for zkApps.
+
+```sql
+, element8          int     REFERENCES zkapp_field(id)
+...
+, element31         int    REFERENCES zkapp_field(id)
+);
+
+```
+
+**Version table**
+
+We also introduced a new table `version` to keep track of the database schema version.
+Purpose of this table is to help with future database migrations. 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.
+
+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.
+
+```sql
+CREATE TABLE IF NOT EXISTS version (
+    version_num INT PRIMARY KEY,
+    applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+```

docs/mesa-upgrade/archive-upgrade.mdx

@@ -0,0 +1,108 @@
+---
+title: Archive Upgrade
+sidebar_label: Archive Upgrade
+hide_title: true
+description: A guide on how to upgrade your Mina archive node to the Mesa version.
+keywords:
+  - Mesa
+  - upgrade
+  - archive
+  - mina archive node
+  - archive node
+---
+
+# Archive Upgrade
+
+To successfully upgrade the archive database into the Mesa version of the Mina network, you must ensure that your environment meets the foundational requirements.
+
+## Migration 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
+- gsutil application from Google Cloud Suite in version 5 or later
+- (Optional) Docker in version 23.0 or later
+
+## 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,
+you can always download it from the O1Labs Google Cloud bucket.
+
+## Upgrade process
+
+### Upgrade script
+
+Assuming that you have a PostgreSQL database with Mainnet archive data, in order to upgrade it to Mesa version, you need to run SQL upgrade script.
+We put all efforts to make the upgrade process as smooth as possible. Script can be run on archive node which is online or offline.
+Script can be run multiple times, it will skip steps that were already completed. It also performs sanity checks before each step to ensure that the upgrade process is successful.
+Finally it creates new table (version) in the database to keep track of the upgrade process.
+
+#### Getting the script
+
+You can find the SQL upgrade script in the Mina repository on GitHub. Make sure to download the latest version of the script before proceeding.
+You can download the script directly using the following command:
+
+```bash
+curl -O https://raw.githubusercontent.com/MinaProtocol/mina/main/src/app/archive_postgres/upgrade/migration.sql
+```
+
+We also ship the script in the Mina archive Docker image and Debian package.
+
+```bash
+docker run --rm minaprotocol/mina-archive:4.0.0-ae112d3-bullseye-mainnet cat /usr/local/bin/migration.sql > migration.sql
+```
+
+```bash
+ # setup the Mina repository and install the archive package
+
+ apt-get install mina-archive
+ cat /etc/mina/archive/upgrade-to-mesa.sql
+ cat /etc/mina/archive/downgrade-to-berkeley.sql
+
+```
+
+#### Running the script
+
+To run the rollback script, you need to execute the following command:
+
+```bash
+psql -U <username> -d <database> -f /etc/mina/archive/downgrade-to-berkeley.sql
+```
+
+Make sure to replace `<username>` and `<database>` with your actual PostgreSQL username and database name.
+
+
+#### 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.
+It will also update the version table to reflect the rollback.
+
+##### Running the rollback script
+
+To run the rollback script, you need to execute the following command:
+
+```bash
+psql -U <username> -d <database> -f /etc/mina/archive/downgrade-to-berkeley.sql
+```
+
+Make sure to replace `<username>` and `<database>` with your actual PostgreSQL username and database name.
+
+
+### Post-upgrade steps
+
+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.
+
+You can do this by running the following command:
+```bash
+psql -U <username> -d <database> -c "SELECT * FROM version;"
+```
+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.
+
+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).

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.