Rewrite Rosetta API docs and fix devnet crash by dkijania · Pull Request #1168 · MinaProtocol/docs2

dkijania · 2026-03-15T20:02:07Z

Summary

Fixes Devnet Rosetta Docker images crash with epoch ledger "Tarball hash mismatch" mina#18600 — devnet Rosetta Docker images crash with "Tarball hash mismatch" due to incorrect MINA_GENESIS_LEDGER_URL in the docs
Complete rewrite of the Rosetta page with proper setup guides, architecture overview, and multiple installation methods

Changes

Fix: Remove MINA_GENESIS_LEDGER_URL from devnet example — the image already contains the correct genesis config; overriding it with an outdated URL causes the crash
Fix: Update image versions (mainnet 3.3.0 -> 3.3.1, add correct devnet tag)
Add: Architecture overview (daemon, archive, PostgreSQL, Rosetta API with ports)
Add: Three installation methods — all-in-one Docker, Docker Compose (production), Debian packages
Add: Environment variables reference table
Add: Offline mode, demo mode, and API verification examples
Add: Available images table with current tags
Fix: Code snippets from indented blocks to fenced code blocks

Test plan

Verify mainnet Docker command works: docker run ... minaprotocol/mina-rosetta:3.3.1-7b34378-focal-mainnet
Verify devnet Docker command works without MINA_GENESIS_LEDGER_URL
Verify Rosetta API responds on port 3087 after sync
Review page renders correctly on localhost

🤖 Generated with Claude Code

Fixes: MinaProtocol/mina#18600 Rewrite the Rosetta page to be more useful and fix the devnet crash caused by an incorrect MINA_GENESIS_LEDGER_URL in the docs: - Remove MINA_GENESIS_LEDGER_URL from devnet example (was causing "Tarball hash mismatch" crash — the image already has the correct genesis config baked in) - Update image versions: mainnet 3.3.0 -> 3.3.1, add devnet tag - Add architecture overview explaining the 4 components and their ports - Add three installation methods: all-in-one Docker (getting started), Docker Compose (production), and Debian packages (manual) - Document supported environment variables with defaults - Add offline mode and demo mode sections - Add API verification examples (network/list, network/status, account/balance) - Add available images table with current tags - Fix code snippets from indented blocks to fenced code blocks Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel · 2026-03-15T20:02:14Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs2	Error		Mar 23, 2026 0:59am

…PI examples - Target master branch for all Mina repo links instead of develop - Replace focal/bullseye with noble/bookworm in Docker images and apt repo - Split verifying API section into individual command snippets - Update Rosetta link to coinbase/mesh-specifications Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

glyh · 2026-03-16T11:40:35Z

docs/node-operators/data-and-history/rosetta.mdx

 </Subhead>

-[Rosetta API](https://www.rosetta-api.org/) is an open-source specification and set of tools that make deploying and interacting with the blockchain quickly and easily.
+[Rosetta API](https://github.com/coinbase/mesh-specifications) is an open-source specification and set of tools that make deploying and interacting with blockchains quick and easy. Mina's Rosetta implementation provides a standard interface for:


I think it's a bad idea to point people to mesh, even if it's just rebranded.

Can you give some reasoning, why you think we shouldn't point to repo ?

I don't have a good enough argument, but I do think it'll be better to point out that we implement a subset of rosetta. And rosetta is rebranded by coinbase to mesh.

This will make user beaware of some API endpoints are not implemented by us at all.

Ok additional information make sense

glyh · 2026-03-16T11:50:20Z

docs/node-operators/data-and-history/rosetta.mdx

- Building blockchain applications, such as explorers and wallets
+- **Exchanges** — integrate MINA deposits, withdrawals, and balance queries
+- **Explorers and wallets** — query historical block and transaction data
+- **Infrastructure operators** — build and submit transactions programmatically


I mean, there's really nothing you can't do with GraphQL and Archive alone, the sole reason we have Rosetta is so exchange is happy.

I would be grateful if a comment was shaped in a way to tell me if i need to remove it or not? From above i need to deduct that it should be removed but it's not clear if this is general comment or criticism of rosetta alone or action point for the docs ?

I guess we can leave it as is, but extend the fact that Rosetta API is an auxilary to our existing GraphQL API.

docs/node-operators/data-and-history/rosetta.mdx

glyh · 2026-03-16T11:56:20Z

docs/node-operators/data-and-history/rosetta.mdx

+| `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)


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.

Was this implemented? I see no modification on docs/exchange-operators/rosetta/docker-compose.mdx and it's not removed either.

ups. I think i didn't commit this part. let me fix it

glyh · 2026-03-16T11:57:38Z

docs/node-operators/data-and-history/rosetta.mdx

+
+| Variable | Default | Description |
+|---|---|---|
+| `MINA_NETWORK` | `mainnet` | Network to connect to (`mainnet` or `devnet`) |


It's very bad, that we have this env var. I would consider just removing this. Because currently profile are compiled into the binary, no?

Also, I would consider moving these from a bash script into OCaml's end, there's no good reason to have a different interface in docker and in debian/native executable. It simply doesn't make sense to me.

Agree, but this is more a comment to mina code not docs. with current implementation we must set MINA_NETWORK if we want to operate on devnet network.

However, agree 100% we need to fix it in mina repo. Will create sufficient pr/issue

If we intend to fix them later, maybe just don't expose it so end-user will not be relying on it?

but MINA_NETWORK must be set if we want to deal with devnet data, otherwise you can use configuration : devnet docker with mainnet network and this will cause a crash

Let's keep it as is for now, I guess

glyh · 2026-03-17T04:58:25Z

docs/node-operators/data-and-history/rosetta.mdx

 The Rosetta stack consists of four components that work together:

-| Component | Port | Description |
+| Component | Default Port | Description |


It might also worth pointing out these ports are the port inside the docker.

- Clarify Mina implements a subset of Rosetta spec, mention Mesh rebrand - Add note that Rosetta is auxiliary to GraphQL API, exists for exchanges - Note that ports are defaults inside Docker container - Keep sync time estimation (20min-1hr) - Remove environment variables section to avoid exposing internal config that users should not rely on Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

dkijania · 2026-03-19T22:50:28Z

@glyh can you rereview ?

glyh · 2026-03-20T13:46:36Z

docs/node-operators/data-and-history/rosetta.mdx

+[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). Everything achievable through Rosetta can also be done with GraphQL and the Archive Node directly. Rosetta exists primarily to satisfy exchange integration requirements.


That's not true though. GraphQL API doesn't have persistence information that's only retrivable via Archive database or Rosetta.

Ok , changing

glyh · 2026-03-20T13:48:35Z

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.

Could you implement this? If not, could you provide some reasoning?

dkijania · 2026-03-23T12:40:56Z

Could you implement this? If not, could you provide some reasoning?

@glyh I've added it in commit: a3fc81c .

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.

glyh · 2026-03-23T12:47:31Z

Opps, sorry I must've missed that section

GraphQL only provides current network state; historical/persistence data requires the Archive database or Rosetta. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview – docs2 March 15, 2026 20:03 View deployment

dkijania self-assigned this Mar 16, 2026

vercel bot deployed to Preview – docs2 March 16, 2026 10:06 View deployment

Format API verification curl commands as multi-line

05c7bdf

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview – docs2 March 16, 2026 10:20 View deployment

glyh reviewed Mar 16, 2026

View reviewed changes

docs/node-operators/data-and-history/rosetta.mdx Outdated Show resolved Hide resolved

glyh reviewed Mar 16, 2026

View reviewed changes

docs/node-operators/data-and-history/rosetta.mdx Show resolved Hide resolved

glyh reviewed Mar 16, 2026

View reviewed changes

docs/node-operators/data-and-history/rosetta.mdx Show resolved Hide resolved

glyh reviewed Mar 16, 2026

View reviewed changes

docs/node-operators/data-and-history/rosetta.mdx Outdated Show resolved Hide resolved

glyh reviewed Mar 16, 2026

View reviewed changes

fix review remarks

a3fc81c

vercel bot deployed to Preview – docs2 March 16, 2026 22:43 View deployment

dkijania requested a review from glyh March 16, 2026 22:43

glyh reviewed Mar 17, 2026

View reviewed changes

vercel bot deployed to Preview – docs2 March 17, 2026 22:14 View deployment

docs(rosetta): restore environment variables table

3fc1746

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot deployed to Preview – docs2 March 17, 2026 22:16 View deployment

dkijania requested a review from glyh March 17, 2026 22:21

glyh reviewed Mar 20, 2026

View reviewed changes

glyh approved these changes Mar 23, 2026

View reviewed changes

docs(rosetta): clarify GraphQL vs Archive data availability

30b7b5d

GraphQL only provides current network state; historical/persistence data requires the Archive database or Rosetta. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vercel bot had a problem deploying to Preview – docs2 March 23, 2026 12:59 Failure

Conversation

dkijania commented Mar 15, 2026

Summary

Changes

Test plan

Uh oh!

vercel bot commented Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glyh Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkijania Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkijania commented Mar 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glyh commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dkijania commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

glyh commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel bot commented Mar 15, 2026 •

edited

Loading

glyh Mar 17, 2026 •

edited

Loading

dkijania Mar 17, 2026 •

edited

Loading

glyh commented Mar 20, 2026 •

edited

Loading

dkijania commented Mar 23, 2026 •

edited

Loading