Skip to content

Commit ccabdf6

Browse files
dkijaniadkijania
committed
added initial draft for upgrade to mesa
1 parent 84ab609 commit ccabdf6

File tree

6 files changed

+499
-0
lines changed

6 files changed

+499
-0
lines changed

‎docs/mesa-upgrade/appendix.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Appendix
3+
sidebar_label: Appendix
4+
hide_title: true
5+
description: Mesa Upgrade Appendix
6+
keywords:
7+
- Mesa
8+
- upgrade
9+
- appendix
10+
---
11+
12+
# Appendix
13+
14+
## Upgrading archive nodes from Berkeley to Mesa
15+
16+
Below we presents details what was changed in the archive node database schema between Berkeley and Mesa version.
17+
18+
**Zkapp_state_nullable additional Columns **
19+
- 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.
20+
21+
```sql
22+
, element8 int REFERENCES zkapp_field(id)
23+
...
24+
, element31 int REFERENCES zkapp_field(id)
25+
);
26+
27+
```
28+
29+
**Version table**
30+
31+
We also introduced a new table `version` to keep track of the database schema version.
32+
Purpose of this table is to help with future database migrations. Table tracks which migration scripts were applied and when.
33+
Ultimately it helps to determine the current version of the database schema. And helps to avoid applying the same migration script multiple times.
34+
35+
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.
36+
37+
```sql
38+
CREATE TABLE IF NOT EXISTS version (
39+
version_num INT PRIMARY KEY,
40+
applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
41+
);
42+
```

‎docs/mesa-upgrade/archive-upgrade.mdx‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Archive Upgrade
3+
sidebar_label: Archive Upgrade
4+
hide_title: true
5+
description: A guide on how to upgrade your Mina archive node to the Mesa version.
6+
keywords:
7+
- Mesa
8+
- upgrade
9+
- archive
10+
- mina archive node
11+
- archive node
12+
---
13+
14+
# Archive Upgrade
15+
16+
To successfully upgrade the archive database into the Mesa version of the Mina network, you must ensure that your environment meets the foundational requirements.
17+
18+
## Migration host
19+
20+
- PostgreSQL database for database server
21+
- 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
22+
- gsutil application from Google Cloud Suite in version 5 or later
23+
- (Optional) Docker in version 23.0 or later
24+
25+
## Archive database
26+
27+
One of the most obvious prerequisites is a Mainnet database. If you don't have an existing database with Devnet/Mainnet archive data,
28+
you can always download it from the O1Labs Google Cloud bucket.
29+
30+
## Upgrade process
31+
32+
### Upgrade script
33+
34+
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.
35+
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.
36+
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.
37+
Finally it creates new table (version) in the database to keep track of the upgrade process.
38+
39+
#### Getting the script
40+
41+
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.
42+
You can download the script directly using the following command:
43+
44+
```bash
45+
curl -O https://raw.githubusercontent.com/MinaProtocol/mina/main/src/app/archive_postgres/upgrade/migration.sql
46+
```
47+
48+
We also ship the script in the Mina archive Docker image and Debian package.
49+
50+
```bash
51+
docker run --rm minaprotocol/mina-archive:4.0.0-ae112d3-bullseye-mainnet cat /usr/local/bin/migration.sql > migration.sql
52+
```
53+
54+
```bash
55+
# setup the Mina repository and install the archive package
56+
57+
apt-get install mina-archive
58+
cat /etc/mina/archive/upgrade-to-mesa.sql
59+
cat /etc/mina/archive/downgrade-to-berkeley.sql
60+
61+
```
62+
63+
#### Running the script
64+
65+
To run the rollback script, you need to execute the following command:
66+
67+
```bash
68+
psql -U <username> -d <database> -f /etc/mina/archive/downgrade-to-berkeley.sql
69+
```
70+
71+
Make sure to replace `<username>` and `<database>` with your actual PostgreSQL username and database name.
72+
73+
74+
#### Rollback
75+
76+
You can rollback the upgrade process by restoring the database from a backup taken before running the upgrade script.
77+
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.
78+
It will also update the version table to reflect the rollback.
79+
80+
##### Running the rollback script
81+
82+
To run the rollback script, you need to execute the following command:
83+
84+
```bash
85+
psql -U <username> -d <database> -f /etc/mina/archive/downgrade-to-berkeley.sql
86+
```
87+
88+
Make sure to replace `<username>` and `<database>` with your actual PostgreSQL username and database name.
89+
90+
91+
### Post-upgrade steps
92+
93+
After successfully running the upgrade script, you DO NOT need to restart your archive node or Rosetta API.
94+
Changes in upgrade script are backward compatible and will be picked up by the archive node and Rosetta API automatically.
95+
96+
### Verification
97+
To verify that the upgrade was successful, you can check the version table in the PostgreSQL database.
98+
99+
You can do this by running the following command:
100+
```bash
101+
psql -U <username> -d <database> -c "SELECT * FROM version;"
102+
```
103+
Make sure to replace `<username>` and `<database>` with your actual PostgreSQL username and database name.
104+
105+
If the upgrade was successful, you should see the new version number in the output.
106+
107+
We put a lot of effort into making the upgrade process as smooth as possible.
108+
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‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: Post-Upgrade Flags and Configurations for Mainnet
3+
sidebar_label: Post-Upgrade Flags and Configurations
4+
hide_title: true
5+
description: Post-Upgrade Flags and Configurations for Mainnet
6+
keywords:
7+
- Berkeley
8+
- upgrade
9+
- flags
10+
- configurations
11+
---
12+
13+
# Post-Upgrade Flags and Configurations for Mainnet
14+
15+
Please refer to the Berkeley node release notes [here](https://github.com/MinaProtocol/mina/releases/tag/3.0.3).
16+
17+
### Network details
18+
19+
```
20+
Chain ID
21+
a7351abc7ddf2ea92d1b38cc8e636c271c1dfd2c081c637f62ebc2af34eb7cc1
22+
23+
Git SHA-1
24+
ae112d3a96fe71b4ccccf3c54e7b7494db4898a4
25+
26+
Seed List
27+
https://bootnodes.minaprotocol.com/networks/mainnet.txt
28+
29+
Node build
30+
https://github.com/MinaProtocol/mina/releases/tag/3.0.3
31+
```
32+
33+
### Block Producer's
34+
35+
Start your node post-upgrade in Mainnet with the flags and environment variables listed below.
36+
37+
```
38+
mina daemon
39+
--block-producer-key <path to the wallet private key file>
40+
--config-directory <path to the mina configuration directory>
41+
--file-log-rotations 500
42+
--generate-genesis-proof true
43+
--libp2p-keypair <keyfile path>
44+
--log-json
45+
--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt
46+
47+
ENVIRONMENT VARIABLES
48+
RAYON_NUM_THREADS=6
49+
MINA_LIBP2P_PASS
50+
MINA_PRIVKEY_PASS
51+
```
52+
53+
### SNARK Coordinator
54+
Configure your node post-upgrade in Mainnet with specific flags and environment variables as listed.
55+
56+
```
57+
mina daemon
58+
--config-directory <path to the mina configuration directory>
59+
--enable-peer-exchange true
60+
--file-log-rotations 500
61+
--libp2p-keypair <keyfile path>
62+
--log-json
63+
--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt
64+
--run-snark-coordinator <public key>
65+
--snark-worker-fee 0.001
66+
--work-selection [seq|rand|roffset]
67+
68+
ENVIRONMENT VARIABLES
69+
MINA_LIBP2P_PASS
70+
```
71+
72+
### SNARK Workers
73+
Connect to a SNARK Coordinator node if required and run the following flags.
74+
```
75+
mina internal snark-worker
76+
--proof-level full
77+
--shutdown-on-disconnect false
78+
--daemon-address <snark coordinator IP:port>
79+
80+
ENVIRONMENT VARIABLES
81+
RAYON_NUM_THREADS:8
82+
```
83+
84+
### Archive Node
85+
Running an Archive Node involves setting up a non-block-producing node and a PostgreSQL database configured with specific flags and environment variables.
86+
87+
For more information about running archive nodes, see [Archive Node](/node-operators/archive-node).
88+
89+
The PostgreSQL database requires two schemas:
90+
1. The PostgreSQL schema used by the Mina archive database: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.3)
91+
2. The PostgreSQL schema extensions to support zkApp commands: in the [release notes](https://github.com/MinaProtocol/mina/releases/tag/3.0.3)
92+
93+
The non-block-producing node must be configured with the following flags:
94+
```
95+
mina daemon
96+
--archive-address <archive_address>:<archive_port - use 3086>
97+
--config-directory <path to mina config>
98+
--enable-peer-exchange true
99+
--file-log-rotations 500
100+
--generate-genesis-proof true
101+
--libp2p-keypair <keyfile path>
102+
--log-json
103+
--peer-list-url https://bootnodes.minaprotocol.com/networks/mainnet.txt
104+
105+
ENVIRONMENT VARIABLES
106+
MINA_LIBP2P_PASS
107+
```
108+
109+
This non-block-producing node connects to the archive node with the addresses and port specified in the `--archive-address` flag.
110+
111+
The **archive node** command looks like this:
112+
113+
```
114+
mina-archive run
115+
--metrics-port <port>
116+
--postgres-uri postgres://<user>:<password>@<address>:<port>/<db>
117+
--server-port 3086
118+
--log-json
119+
--log-level DEBUG
120+
```
121+
122+
### Rosetta API
123+
Once you have the Archive Node stack up and running, start the Rosetta API Docker image with the following command:
124+
125+
```
126+
docker run
127+
--name rosetta --rm \
128+
-p 3088:3088 \
129+
--entrypoint '' \
130+
minaprotocol/mina-rosetta:3.1.0-ae112d3-bullseye-mainnet \
131+
/usr/local/bin/mina-rosetta \
132+
--archive-uri "${PG_CONNECTION_STRING}" \
133+
--graphql-uri "${GRAPHQL_URL}" \
134+
--log-json \
135+
--log-level ${LOG_LEVEL} \
136+
--port 3088
137+
```

‎docs/mesa-upgrade/requirements.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Requirements
3+
sidebar_label: Requirements
4+
hide_title: true
5+
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.
6+
keywords:
7+
- Berkeley
8+
- upgrade
9+
- hardware requirements
10+
---
11+
12+
# Requirements
13+
14+
## Hardware Requirements
15+
16+
Please note the following are the hardware requirements for each node type after the upgrade:
17+
18+
| Node Type | Memory | CPU | Storage | Network |
19+
|--|--|--|--|--|
20+
| Mina Daemon Node | 32 GB RAM | 8 core processor with BMI2 and AVX CPU instruction set are required | 64 GB | 1 Mbps Internet Connection |
21+
| SNARK Coordinator | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection |
22+
| 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 |
23+
| Archive Node | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection |
24+
| Rosetta API standalone Docker image | 32 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection |
25+
| Mina Seed Node | 64 GB RAM | 8 core processor | 64 GB | 1 Mbps Internet Connection |
26+
27+
## Mina Daemon Requirements
28+
29+
### Installation
30+
31+
:::caution
32+
33+
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`.
34+
The `mina-generate-keypair` binary is now installed as part of the mina-mainnet package.
35+
36+
:::
37+
38+
### IP and Port configuration
39+
40+
**IP:**
41+
42+
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.
43+
44+
**Port:**
45+
46+
Nodes must expose a port publicly to communicate with other peers.
47+
Mina uses by default the port `8302` which is the default libp2p port.
48+
49+
You can use a different port by setting the `--external-port` flag.
50+
51+
### Node Auto-restart
52+
53+
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)
54+
55+
## Seed Peer Requirements
56+
57+
### Generation of libp2p keypair
58+
59+
To ensure connectivity across the network, it is essential that all seed nodes start with the **same** `libp2p` keypair.
60+
This consistency allows other nodes in the network to reliably connect.
61+
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:
62+
63+
```
64+
mina libp2p generate-keypair --privkey-path <path-to-the-key-file>
65+
```
66+
67+
Further information on [generating key pairs](/node-operators/generating-a-keypair) on Mina Protocol.

0 commit comments

Comments
 (0)