Cardano Rosetta Java

High-performance Java implementation of the Mesh API (formerly Rosetta) for Cardano blockchain integration.

Overview

Cardano Rosetta Java provides a production-grade implementation of the Mesh API specification (formerly Rosetta) for the Cardano blockchain. Built with Java and powered by Yaci-Store, it offers significantly lower resource consumption compared to alternative implementations.

Architecture

graph LR
    Client[Client]
    
    subgraph "Core Components"
        API[rosetta-api<br/>:8082]
        Indexer[yaci-indexer<br/>:9095]
        DB[(postgres<br/>:5432)]
        Node[cardano-node<br/>:3001]
        Submit[submit-api<br/>:8090]
        
        API -->|query| Indexer
        Indexer -->|store| DB
        Indexer -->|sync| Node
        API -->|submit tx| Submit
        Submit -->|broadcast| Node
    end
    
    Client -->|REST| API
    Node -->|P2P| Network[Cardano<br/>Network]
    
    Mithril[mithril] -.->|bootstrap| Node
    Monitoring[monitoring<br/>:3000/:9090] -.-> API
    
    style Client fill:#ffffff,stroke:#000000,stroke-width:2px,color:#000
    style API fill:#ff0000,stroke:#000000,stroke-width:2px,color:#fff
    style Indexer fill:#f5f5f5,stroke:#000000,stroke-width:2px,color:#000
    style DB fill:#000000,stroke:#000000,stroke-width:2px,color:#fff
    style Node fill:#f5f5f5,stroke:#000000,stroke-width:2px,color:#000
    style Submit fill:#f5f5f5,stroke:#000000,stroke-width:2px,color:#000
    style Network fill:#ffffff,stroke:#000000,stroke-width:2px,color:#000
    style Mithril fill:#e6e6ff,stroke:#999999,stroke-width:1px,color:#000
    style Monitoring fill:#ffe6e6,stroke:#999999,stroke-width:1px,color:#000

Loading

Key Features

• Mesh API (Rosetta) compliant for standardized blockchain integration
• All-in-one Docker Compose deployment with node, indexer, and API
• Spent UTXO pruning support reducing storage by ~40%
• Offline mode for secure transaction construction
• Native asset support including NFTs and custom tokens
• Governance operations for Conway era features (DRep vote delegation, Pool governance vote)
• SPO operations for stake pool features (registration, deregistration, retirement, update, etc.)

Quick Start

Important

Starting from v1.4.0, Spent UTXO Pruning is enabled by default to optimize for exchange operations:

• Maintains complete current UTXO set and recent history (default: 30 days)
• Historical block/transaction queries return incomplete data beyond the safety margin
• Transaction search by hash always works, address search limited to recent history

To keep full history, set REMOVE_SPENT_UTXOS=false in your env file.

Preprod Testnet (~3 hours sync time)

Prerequisites

• Docker and Docker Compose
• 4+ CPU cores, 32GB RAM
• 100GB storage (pruning enabled) or 140GB (pruning disabled)

Steps

1. Clone and launch

git clone https://github.com/cardano-foundation/cardano-rosetta-java.git
cd cardano-rosetta-java

docker compose --env-file .env.docker-compose-preprod \
  --env-file .env.docker-compose-profile-entry-level \
  -f docker-compose.yaml up -d

2. Monitor sync progress

# Check sync status
curl -X POST http://localhost:8082/network/status \
  -H "Content-Type: application/json" \
  -d '{"network_identifier": {"blockchain": "cardano", "network": "preprod"}}'

# View logs (merge env files to avoid warnings)
cat .env.docker-compose-preprod .env.docker-compose-profile-entry-level > .env
docker compose logs -f

Mainnet (ca. 37 hours sync time with Mithril)

Prerequisites

• Docker and Docker Compose
• 8+ CPU cores, 48GB RAM
• 750GB storage (pruning enabled) or 1.3TB (pruning disabled)

Steps

1. Clone and launch

git clone https://github.com/cardano-foundation/cardano-rosetta-java.git
cd cardano-rosetta-java

docker compose --env-file .env.docker-compose \
  --env-file .env.docker-compose-profile-mid-level \
  -f docker-compose.yaml up -d

2. Monitor sync progress

# Check sync status
curl -X POST http://localhost:8082/network/status \
  -H "Content-Type: application/json" \
  -d '{"network_identifier": {"blockchain": "cardano", "network": "mainnet"}}'

# View logs (merge env files to avoid warnings)
cat .env.docker-compose .env.docker-compose-profile-mid-level > .env
docker compose logs -f

Note

Mithril snapshots are used automatically to accelerate initial sync. Full sync times vary based on hardware and network conditions.

System Requirements

Based on our hardware profiles:

Profile	CPU	RAM	Storage (Pruning Enabled)	Storage (Pruning Disabled)	Use Case
Entry-Level	4 cores	32GB	100GB (preprod)	140GB (preprod)	Development & testing
Mid-Level ⭐	8 cores	48GB	750GB (mainnet)	1.3TB (mainnet)	Production (recommended)
Advanced	16 cores	94GB	750GB (mainnet)	1.3TB (mainnet)	High-volume exchanges

Installation

Docker Compose (Recommended)

See Quick Start above or the installation documentation.

Other Methods

• Pre-built Docker images: DockerHub
• Build from source: Documentation

Configuration

Key Settings

Variable	Description	Default
CARDANO_NETWORK	Network to connect to	mainnet
API_SPRING_PROFILES_ACTIVE	API mode (online/offline)	online
REMOVE_SPENT_UTXOS	Enable spent UTXO pruning	true
REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT	Safety margin for pruning (in blocks)	129600 (~30 days)
API_PORT	Mesh API port	8082

Check environment variable reference for details.

API Usage & Operations

Common Operations

Check Network Status

curl -X POST http://localhost:8082/network/status \
  -H "Content-Type: application/json" \
  -d '{"network_identifier": {"blockchain": "cardano", "network": "mainnet"}}'

Get Account Balance

curl -X POST http://localhost:8082/account/balance \
  -H "Content-Type: application/json" \
  -d '{
    "network_identifier": {"blockchain": "cardano", "network": "mainnet"},
    "account_identifier": {"address": "addr1..."}
  }'

Submit Transaction

curl -X POST http://localhost:8082/construction/submit \
  -H "Content-Type: application/json" \
  -d '{
    "network_identifier": {"blockchain": "cardano", "network": "mainnet"},
    "signed_transaction": "..."
  }'

Monitoring & Troubleshooting

Health Checks

# Container status
docker compose ps

# Service logs
docker compose logs -f api
docker compose logs -f yaci-indexer
docker compose logs -f cardano-node

Common Issues

Symptom	Possible Cause	Action
API returns 503	Services still starting	Wait 2-3 minutes for initialization, check docker compose logs
Incorrect balances	Node not fully synced	Verify sync with /network/status, check current_block_identifier vs network tip
Transaction submission fails	Invalid CBOR or network mismatch	Verify transaction format, ensure correct network in network_identifier
High memory usage	Insufficient resources for profile	Switch to lower profile or increase RAM allocation
Disk space warnings	Pruning disabled or safety margin too large	Enable pruning (REMOVE_SPENT_UTXOS=true) or reduce safety margin
Historical queries return incomplete data	Pruning enabled (by design)	Check oldest_block_identifier in /network/status for fully queryable range

Documentation & Support

• Full Documentation
• Mesh API Reference
• Cardano Specific API Additions
• Hardware Profiles
• GitHub Issues
• GitHub Discussions

License

Apache License 2.0

---

Built with ❤️ by the Cardano Foundation