Archive Nodes Getting Started
Mina nodes are succinct by default, so they don't need to maintain historical information about the network, block, or transactions.
For some use cases, it is useful to maintain this historical data on an archive node.
A zkApp can retrieve events and actions from one or more Mina archive nodes. If your smart contract needs to fetch events and actions from an archive node, see How to Fetch Events and Actions.
An archive node is a regular mina daemon that is connected to a running mina-archive process using the --archive-address flag.
The daemon regularly sends blockchain data to the archive process that stores it in a PostgreSQL database.
Archive Node Requirements
Software: Supported environments include macOS, Linux (Debian 10, 11 and Ubuntu 20.04 LTS), and any host machine with Docker.
Processor: Only x86-64 CPU architecture is supported.
Hardware: Running an archive node does not require any special hardware.
In addition to the PostgreSQL database requirements, running an archive node on the Mina network requires at least:
- 8-core processor
- 32 GB of RAM
- 64 GB of free storage
Running an archive node requires some knowledge of managing a PostgreSQL database instance. You must set up a database, run the archive node, connect it to a daemon, and run queries on the data.
Install Mina, PostgreSQL, and the archive node package
Install the latest version of Mina.
You must upgrade to the latest version of the daemon. Follow the steps in Getting Started.
Download and install PostgreSQL.
Install the archive node package.
Ubuntu/Debian:
sudo apt-get install mina-archive=3.0.3-d800da8Docker:
minaprotocol/mina-archive:3.0.3-d800da8-bullseye
Set up the archive node
These steps might be different for your operating system, if you're connecting to a cloud instance of PostgreSQL, if your deployment uses Docker, or if you want to run these processes on different machines.
For production, run the archive database in the background, use your operating system service manager (like systemd) to run it for you, or use a postgres service hosted by a cloud provider.
To run a local archive node to run it in the foreground for testing:
Start a local postgres server and connect to port 5432:
postgres -p 5432 -D /usr/local/var/postgresFor macOS:
brew services start postgresCreate a local postgres database called
archive:psql -p 5432 --h localhost -c "create database archive"Load the mina archive schema into the archive database, (create_schema.sql and zkapp_tables.sql):
psql -h localhost -p 5432 -d archive -f <(curl -Ls https://raw.githubusercontent.com/MinaProtocol/mina/release/3.0.2/src/app/archive/create_schema.sql)Start the archive process on port 3086 and connect to the postgres database that runs on port 5432:
mina-archive run \
--postgres-uri postgres://localhost:5432/archive \
--server-port 3086Start the mina daemon and connect it to the archive process that you started on port 3086:
mina daemon \
.....
--archive-address 3086To connect to an archive process on another machine, specify a hostname with <ipaddress:portnumber> i.e.
154.97.53.97:3086.
Set up the archive node using Docker
To get started with installing and running the archive node using Docker, follow the steps below.
Install Docker on your machine. For more information, see Docker.
Pull the archive node image from Docker Hub.
docker pull minaprotocol/mina-archive:3.0.3-d800da8-bullseyePull and install the postgres image from Docker Hub.
docker pull postgresStart the postgres container and expose it's networking to other containers.
docker run --name postgres -p 5432:5432 -e POSTGRES_PASSWORD=postgres -d postgresCreate a local postgres database called
archive.docker exec -it postgres createdb -U postgres archiveLoad the mina archive schemas into the archive database, (create_schema.sql and zkapp_tables.sql.)
curl -Ls https://raw.githubusercontent.com/MinaProtocol/mina/1551e2faaa246c01636908aabe5f7981715a10f4/src/app/archive/create_schema.sql | docker exec -i postgres psql -U postgres -d archive
curl -Ls https://raw.githubusercontent.com/MinaProtocol/mina/1551e2faaa246c01636908aabe5f7981715a10f4/src/app/archive/zkapp_tables.sql | docker exec -i postgres psql -U postgres -d archiveCreate a local directory to store the archive node data.
mkdir -p /tmp/archiveStart the archive node.
docker run \
--name archive \
-p 3086:3086 \
-v /tmp/archive:/data \
minaprotocol/mina-archive:3.0.3-d800da8-bullseye \
mina-archive run \
--postgres-uri postgres://postgres:postgres@postgres:5432/archive \
--server-port 3086
:::warning
Please be careful when using --config argument at archive node bootstrap.
It should be provided only when archive node is connected to short lived network created mainly for testing, local development or experimental networks.
Never use it on long lived network such as mainnet or devnet
:::
Start the mina daemon and connect it to the archive process that you started on port 3086:
mina daemon \
.....
--archive-address 3086To connect to an archive process on another machine, specify a hostname with <ipaddress:portnumber> i.e.
154.97.53.97:3086.
Set up the archive node using Docker Compose
Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services. Then, with a single command, you create and start all the services from your configuration.
To run the archive node using Docker Compose:
Install Docker on your machine. For more information, see Docker.
Install Docker Compose on your machine. For more information, see Docker Compose.
Pull the archive node image from Docker Hub.
docker pull minaprotocol/mina-archive:3.0.3-d800da8-bullseyePull and install the postgres image from Docker Hub.
docker pull postgresCreate a local directory to store the archive node data.
mkdir -p /tmp/archiveCreate a
docker-compose.ymlfile with the following contents:services:
postgres:
image: postgres
environment:
POSTGRES_PASSWORD: postgres
volumes:
- './postgres-data:/var/lib/postgresql/data'
ports:
- '5432:5432'
archive:
image: 'minaprotocol/mina-archive:3.0.3-d800da8-bullseye'
command: >-
mina-archive run --postgres-uri
postgres://postgres:postgres@postgres:5432/archive --server-port 3086
volumes:
- '/tmp/archive:/data'
ports:
- '3086:3086'
depends_on:
- postgresStart the archive node.
docker compose upStart the mina daemon and connect it to the archive process that you started on port 3086:
mina daemon \
.....
--archive-address 3086To connect to an archive process on another machine, specify a hostname with <ipaddress:portnumber> i.e.
154.97.53.97:3086.
Using the Archive Node
Take a look at the tables in the database.
To list the tables, run the \dt command in psql. The output will look like this:
List of relations
Schema | Name | Type | Owner
--------+-------------------------------+-------+-------
public | account_identifiers | table | mina
public | accounts_accessed | table | mina
public | accounts_created | table | mina
public | blocks | table | mina
public | blocks_internal_commands | table | mina
public | blocks_user_commands | table | mina
public | blocks_zkapp_commands | table | mina
public | epoch_data | table | mina
public | internal_commands | table | mina
public | protocol_versions | table | mina
public | public_keys | table | mina
public | snarked_ledger_hashes | table | mina
public | timing_info | table | mina
public | token_symbols | table | mina
public | tokens | table | mina
public | user_commands | table | mina
public | voting_for | table | mina
public | zkapp_account_precondition | table | mina
public | zkapp_account_update | table | mina
public | zkapp_account_update_body | table | mina
public | zkapp_account_update_failures | table | mina
public | zkapp_accounts | table | mina
public | zkapp_action_states | table | mina
public | zkapp_amount_bounds | table | mina
public | zkapp_balance_bounds | table | mina
public | zkapp_commands | table | mina
public | zkapp_epoch_data | table | mina
public | zkapp_epoch_ledger | table | mina
public | zkapp_events | table | mina
public | zkapp_fee_payer_body | table | mina
public | zkapp_field | table | mina
public | zkapp_field_array | table | mina
public | zkapp_global_slot_bounds | table | mina
public | zkapp_length_bounds | table | mina
public | zkapp_network_precondition | table | mina
public | zkapp_nonce_bounds | table | mina
public | zkapp_permissions | table | mina
public | zkapp_states | table | mina
public | zkapp_states_nullable | table | mina
public | zkapp_timing_info | table | mina
public | zkapp_token_id_bounds | table | mina
public | zkapp_updates | table | mina
public | zkapp_uris | table | mina
public | zkapp_verification_key_hashes | table | mina
public | zkapp_verification_keys | table | mina
(45 rows)
Use the \d table_name to look at the structure of a table in the database.
For example to see the structure of the user_commands table, run the \d user_commands command in psql. The output will look like this:
Table "public.user_commands"
Column | Type | Collation | Nullable | Default
--------------+-------------------+-----------+----------+-------------------------------------------
id | integer | | not null | nextval('user_commands_id_seq'::regclass)
command_type | user_command_type | | not null |
fee_payer_id | integer | | not null |
source_id | integer | | not null |
receiver_id | integer | | not null |
nonce | bigint | | not null |
amount | text | | |
fee | text | | not null |
valid_until | bigint | | |
memo | text | | not null |
hash | text | | not null |
Indexes:
"user_commands_pkey" PRIMARY KEY, btree (id)
"user_commands_hash_key" UNIQUE CONSTRAINT, btree (hash)
Foreign-key constraints:
"user_commands_fee_payer_id_fkey" FOREIGN KEY (fee_payer_id) REFERENCES public_keys(id)
"user_commands_receiver_id_fkey" FOREIGN KEY (receiver_id) REFERENCES public_keys(id)
"user_commands_source_id_fkey" FOREIGN KEY (source_id) REFERENCES public_keys(id)
Referenced by:
TABLE "blocks_user_commands" CONSTRAINT "blocks_user_commands_user_command_id_fkey" FOREIGN KEY (user_command_id) REFERENCES user_commands(id) ON DELETE CASCADE
Review the full schema at /archive/create_schema.sql and /archive/zkapp_tables.sql
Query the database
Now that you know the structure of the data, try some queries.
Example 1: Find all blocks that were created by your public key:
SELECT *
FROM blocks AS b
INNER JOIN public_keys AS pk1 ON b.creator_id = pk1.id
WHERE value = 'MY_PK'
Example 2: Find all payments received by your public key:
SELECT *
FROM user_commands AS uc
JOIN blocks_user_commands AS buc ON uc.id = buc.user_command_id
JOIN public_keys AS pk ON uc.receiver_id = pk.id
WHERE value = 'MY_PK'
AND type = 'payment'
Example 3: Find the block at height 12 on the canonical chain:
WITH RECURSIVE chain AS (
(SELECT ... FROM blocks b WHERE height = (select MAX(height) from blocks)
ORDER BY timestamp ASC
LIMIT 1)
UNION ALL
SELECT ... FROM blocks b
INNER JOIN chain
ON b.id = chain.parent_id AND chain.id <> chain.parent_id
) SELECT ..., pk.value as creator FROM chain c
INNER JOIN public_keys pk
ON pk.id = c.creator_id
WHERE c.height = 12
Example 3: List the counts of blocks created by each public key and sort them in descending order"
SELECT p.value, COUNT(*) FROM blocks
INNER JOIN public_keys AS p ON creator_id = ip.id
GROUP BY p.value
ORDER BY count DESC;
Example 4: List the counts of applied payments created by each public key and sort them in descending order:
SELECT p.value, COUNT(*) FROM user_commands
INNER JOIN public_keys AS p ON source_id = p.id
WHERE status = 'applied'
AND type = 'payment'
GROUP BY p.value ORDER BY count DESC;
Example 5 Get the latest block:
SELECT
height as blockheight,
global_slot_since_genesis as globalslotsincegenesis,
global_slot_since_hard_fork as globalslot,
state_hash as statehash,
parent_hash as parenthash,
ledger_hash as ledgerhash,
to_char(to_timestamp(cast ("timestamp" as bigint) / 1000) AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS') || '.' ||
LPAD(((cast("timestamp" as bigint) % 1000)::text), 3, '0') || 'Z' as datetime
FROM blocks
WHERE id in (SELECT MAX(id) FROM blocks);
Example 6 Identify blocks with missing parents, between blockheight 500 and blockheight 5000
SELECT height
FROM blocks
WHERE parent_id is null AND height >= 500 AND height <= 5000 and height > 1;