Rewrite Rosetta API docs and fix devnet crash #1168
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,107 +1,204 @@ | ||
| --- | ||
| title: Rosetta API | ||
| hide_title: true | ||
| description: Install and run Mina's implementation of the Rosetta API for blockchain integration, historical data queries, and exchange support. | ||
| keywords: | ||
| - rosetta | ||
| - API | ||
| - blockchain integration | ||
| - exchange | ||
| - archive node | ||
| - docker | ||
| - historical data | ||
| --- | ||
|
|
||
| # Rosetta API | ||
|
|
||
| import Subhead from "@site/src/components/common/Subhead"; | ||
|
|
||
| <Subhead> | ||
| A standardized API for blockchain integration — query historical data, build transactions, and integrate with exchanges. | ||
| </Subhead> | ||
|
|
||
| [Rosetta API](https://www.rosetta-api.org/) (rebranded as [Mesh](https://docs.cdp.coinbase.com/mesh/docs/welcome/) by Coinbase) is an open-source specification and set of tools that make deploying and interacting with blockchains quick and easy. Mina implements a subset of the Rosetta specification — not all endpoints defined in the spec are available. Mina's Rosetta implementation is primarily used by exchanges to integrate MINA deposits, withdrawals, and balance queries. | ||
|
|
||
| :::note | ||
| The Rosetta API is auxiliary to Mina's existing [GraphQL API](/node-operators/mina-cli-reference) and [Archive Node](/node-operators/archive-node). While GraphQL provides access to current network state, historical and persistence data requires the Archive database. Rosetta bundles both data sources behind a standardized interface and exists primarily to satisfy exchange integration requirements. | ||
| ::: | ||
|
|
||
| ## Architecture | ||
|
|
||
| The Rosetta stack consists of four components that work together: | ||
|
|
||
| | Component | Default Port | Description | | ||
| |---|---|---| | ||
| | **Mina Daemon** | 8302 (P2P), 3085 (GraphQL) | Syncs with the network, produces/validates blocks | | ||
| | **Archive Node** | 3086 | Stores historical block data in PostgreSQL | | ||
| | **PostgreSQL** | 5432 | Database backend for the archive node | | ||
| | **Rosetta API** | 3087 (online), 3088 (offline) | Translates Mina data into the Rosetta specification | | ||
|
|
||
| All ports listed above are defaults and can be overridden via configuration. When using Docker, these are the ports inside the container — map them to your desired host ports with `-p`. | ||
|
|
||
| ## Installation | ||
|
|
||
| There are three ways to run Rosetta, depending on your needs. | ||
|
|
||
| ### Option 1: All-in-One Docker Image (Recommended for getting started) | ||
|
|
||
| The all-in-one image bundles the daemon, archive node, PostgreSQL, and Rosetta API into a single container. It automatically initializes the archive database from public o1Labs backups. | ||
|
|
||
| **Requirements:** Docker with at least 12 GB RAM allocated (16 GB recommended). | ||
|
|
||
|
glyh marked this conversation as resolved.
|
||
| #### Mainnet | ||
|
|
||
| ```bash | ||
| docker run -it --rm --name rosetta \ | ||
| --entrypoint=./docker-start.sh \ | ||
| -p 8302:8302 -p 3085:3085 -p 3086:3086 -p 3087:3087 \ | ||
| minaprotocol/mina-rosetta:3.3.1-7b34378-noble-mainnet | ||
| ``` | ||
|
|
||
| #### Devnet | ||
|
|
||
| ```bash | ||
| docker run -it --rm --name rosetta \ | ||
| --entrypoint=./docker-start.sh \ | ||
| -p 8302:8302 -p 3085:3085 -p 3086:3086 -p 3087:3087 \ | ||
| -e MINA_NETWORK=devnet \ | ||
|
glyh marked this conversation as resolved.
|
||
| -e PEER_LIST_URL=https://bootnodes.minaprotocol.com/networks/devnet.txt \ | ||
| minaprotocol/mina-rosetta:3.2.0-97ad487-bookworm-devnet | ||
| ``` | ||
|
|
||
| Initial sync typically takes between 20 minutes and 1 hour depending on your hardware and network connection. You can check sync status with: | ||
|
|
||
| ```bash | ||
| docker exec rosetta mina client status | ||
| ``` | ||
|
|
||
| #### Environment Variables | ||
|
|
||
| The all-in-one image supports the following environment variables for customization: | ||
|
|
||
| | Variable | Default | Description | | ||
| |---|---|---| | ||
| | `MINA_NETWORK` | `mainnet` | Network to connect to (`mainnet` or `devnet`) | | ||
| | `PEER_LIST_URL` | Network-specific seed list | URL for the peer list | | ||
| | `LOG_LEVEL` | `Debug` | Log level (`Info`, `Debug`, `Warn`, `Error`) | | ||
| | `MINA_GRAPHQL_PORT` | `3085` | GraphQL API port | | ||
| | `MINA_ARCHIVE_PORT` | `3086` | Archive node port | | ||
| | `MINA_ROSETTA_ONLINE_PORT` | `3087` | Rosetta online API port | | ||
| | `MINA_ROSETTA_OFFLINE_PORT` | `3088` | Rosetta offline API port | | ||
| | `POSTGRES_USERNAME` | `pguser` | PostgreSQL username | | ||
| | `POSTGRES_DBNAME` | `archive` | PostgreSQL database name | | ||
| | `POSTGRES_DATA_DIR` | `/data/postgresql` | PostgreSQL data directory | | ||
| | `MINA_ARCHIVE_DUMP_URL` | `https://storage.googleapis.com/mina-archive-dumps` | Base URL for archive database dumps | | ||
| | `MINA_CONFIG_DIR` | `/data/.mina-config` | Mina configuration directory | | ||
|
|
||
| ### Option 2: Docker Compose (Recommended for production) | ||
|
Member
There was a problem hiding this comment. There was a docker compose under this repo in markdown, I suggest we should unify the compose file here with the one we have in repo.
Member
There was a problem hiding this comment. Was this implemented? I see no modification on docs/exchange-operators/rosetta/docker-compose.mdx and it's not removed either.
Member
Author
There was a problem hiding this comment. ups. I think i didn't commit this part. let me fix it |
||
|
|
||
| For production deployments, use Docker Compose to run each component as a separate container. This gives you more control over resource allocation, logging, and restarts. | ||
|
|
||
| For production deployments, a complete Docker Compose configuration with all four services (PostgreSQL, archive node, Mina daemon, and Rosetta API) is available in the [Rosetta Docker Compose guide](/exchange-operators/rosetta/docker-compose). | ||
|
|
||
| ### Option 3: Debian Packages (Manual setup) | ||
|
|
||
| You can install each component individually via Debian packages. This is useful if you already run a Mina daemon and archive node and only need to add the Rosetta API. | ||
|
|
||
| ```bash | ||
| # Add the Mina repository (if not already configured) | ||
| echo "deb [trusted=yes] http://packages.o1test.net/ noble stable" | sudo tee /etc/apt/sources.list.d/mina.list | ||
| sudo apt-get update | ||
|
|
||
| # Install the Rosetta package for your network | ||
| sudo apt-get install mina-rosetta-mainnet | ||
| # or: sudo apt-get install mina-rosetta-devnet | ||
| ``` | ||
|
|
||
| Then run the Rosetta API pointing to your existing daemon and archive database: | ||
|
|
||
| ```bash | ||
| mina-rosetta \ | ||
| --archive-uri postgres://<user>:<password>@<host>:<port>/<db> \ | ||
| --graphql-uri http://localhost:3085/graphql \ | ||
| --log-json \ | ||
| --port 3087 | ||
| ``` | ||
|
|
||
| This requires a running [Mina daemon](/node-operators/block-producer-node) and [archive node](/node-operators/archive-node) with a populated PostgreSQL database. | ||
|
|
||
| ## Offline Mode | ||
|
|
||
| The Rosetta Construction API requires an "offline" endpoint that can build and sign transactions without network access. Use the standalone entrypoint for this: | ||
|
|
||
| ```bash | ||
| docker run -it --rm --name rosetta-offline \ | ||
| --entrypoint=./docker-standalone-start.sh \ | ||
| -p 3088:3088 \ | ||
| minaprotocol/mina-rosetta:3.3.1-7b34378-noble-mainnet | ||
| ``` | ||
|
|
||
| This starts only the Rosetta API process — no daemon, archive, or database. Point your Construction API calls to this endpoint for offline operations. | ||
|
|
||
| ## Demo Mode | ||
|
|
||
| For development and testing, the demo mode launches a local sandbox with a simple genesis ledger and all components running inside a single container: | ||
|
|
||
| ```bash | ||
| docker run -it --rm --name rosetta-demo \ | ||
| --entrypoint=./docker-demo-start.sh \ | ||
| -p 3085:3085 -p 3087:3087 \ | ||
| minaprotocol/mina-rosetta:3.3.1-7b34378-noble-mainnet | ||
| ``` | ||
|
|
||
| This creates an isolated network with no external connectivity — useful for developing integrations before connecting to mainnet or devnet. | ||
|
|
||
| ## Available Images | ||
|
|
||
| | Network | Image | Notes | | ||
| |---|---|---| | ||
| | **Mainnet (noble)** | `minaprotocol/mina-rosetta:3.3.1-7b34378-noble-mainnet` | amd64 | | ||
| | **Mainnet (bookworm)** | `minaprotocol/mina-rosetta:3.3.1-7b34378-bookworm-mainnet` | Also available for arm64 | | ||
| | **Devnet (bookworm)** | `minaprotocol/mina-rosetta:3.2.0-97ad487-bookworm-devnet` | Latest devnet | | ||
|
|
||
| Images are published on [Docker Hub](https://hub.docker.com/r/minaprotocol/mina-rosetta/tags). | ||
|
|
||
| ## Verifying the API | ||
|
|
||
| Once your node is synced, verify the Rosetta API is working. | ||
|
|
||
| **List available networks:** | ||
|
|
||
| ```bash | ||
| curl -s http://localhost:3087/network/list \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{"metadata":{}}' | jq . | ||
| ``` | ||
|
|
||
| **Get network status:** | ||
|
|
||
| ```bash | ||
| curl -s http://localhost:3087/network/status \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{"network_identifier": {"blockchain": "mina", "network": "mainnet"}}' | jq . | ||
| ``` | ||
|
|
||
| **Query an account balance:** | ||
|
|
||
| ```bash | ||
| curl -s http://localhost:3087/account/balance \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "network_identifier": {"blockchain": "mina", "network": "mainnet"}, | ||
| "account_identifier": {"address": "<MINA_ADDRESS>"} | ||
| }' | jq . | ||
| ``` | ||
|
|
||
| ## Building Your Own Image | ||
|
|
||
| For most users, the official images are sufficient. If you need to build a custom image, see the [Rosetta README](https://github.com/MinaProtocol/mina/blob/master/src/app/rosetta/README.md) in the Mina repository for build instructions. | ||
|
|
||
| ## Questions and Support | ||
|
|
||
| - Post questions in [Mina GitHub Discussions](https://github.com/MinaProtocol/mina/discussions) | ||
| - Report bugs on [GitHub Issues](https://github.com/MinaProtocol/mina/issues) | ||
| - Join the [Mina Discord](https://discord.gg/minaprotocol) for community support | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It might also worth pointing out these ports are the port inside the docker.