From 6ffb3830811af2b094e02d475eb64bba57348cfd Mon Sep 17 00:00:00 2001
From: Lincon Vidal <lincon.vidal@cardanofoundation.org>
Date: Fri, 12 Sep 2025 14:58:43 -0300
Subject: [PATCH 1/6] docs: enhance README for clarity and add contributing
 guidelines

- Introduced a new CONTRIBUTING.md file outlining contribution guidelines, development environment setup, and testing procedures.
- Enhanced README.md with updated project overview, key features, quick start instructions, and detailed API usage examples.
- Improved documentation structure for better navigation and clarity, including links to relevant resources and support channels.
---
 CONTRIBUTING.md | 356 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 298 ++++++++++++++++++++++++++++------------
 2 files changed, 564 insertions(+), 90 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..6c8fb1d4e
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,356 @@
+# Contributing to Cardano Rosetta Java
+
+Thank you for your interest in contributing to Cardano Rosetta Java! This document provides guidelines and instructions for contributing to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Environment Setup](#development-environment-setup)
+- [Project Structure](#project-structure)
+- [Making Contributions](#making-contributions)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Code Style Guidelines](#code-style-guidelines)
+- [Reporting Issues](#reporting-issues)
+
+## Code of Conduct
+
+Please read and follow our [Code of Conduct](CODE-OF-CONDUCT.md). We are committed to providing a welcoming and inclusive environment for all contributors.
+
+## Getting Started
+
+1. **Fork the Repository**: Start by forking the [cardano-rosetta-java repository](https://github.com/cardano-foundation/cardano-rosetta-java) to your GitHub account.
+
+2. **Clone Your Fork**:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/cardano-rosetta-java.git
+   cd cardano-rosetta-java
+   ```
+
+3. **Add Upstream Remote**:
+   ```bash
+   git remote add upstream https://github.com/cardano-foundation/cardano-rosetta-java.git
+   ```
+
+## Development Environment Setup
+
+### Prerequisites
+
+- **Java 24** with preview features enabled
+- **Maven 3.9+**
+- **Docker and Docker Compose**
+- **Git**
+- **IDE** with Java support (IntelliJ IDEA recommended)
+
+### Local Development Setup
+
+1. **Install Java 24**:
+   ```bash
+   # Using SDKMAN
+   sdk install java 24-open
+   sdk use java 24-open
+   ```
+
+2. **Build the Project**:
+   ```bash
+   # Build all modules
+   mvn clean install
+   
+   # Build specific module
+   mvn clean install -pl api
+   ```
+
+3. **Run Tests**:
+   ```bash
+   # Run all tests
+   mvn test
+   
+   # Run specific test class
+   mvn test -Dtest=ClassName
+   ```
+
+4. **Run Locally with H2 Database** (for development):
+   ```bash
+   # Set H2 profile
+   export SPRING_PROFILES_ACTIVE=h2
+   
+   # Run the API module
+   cd api
+   mvn spring-boot:run
+   ```
+
+5. **Run with Docker Compose** (full stack):
+   ```bash
+   docker compose --env-file .env.docker-compose-preprod \
+     --env-file .env.docker-compose-profile-mid-level \
+     -f docker-compose.yaml up -d
+   ```
+
+## Project Structure
+
+```
+cardano-rosetta-java/
+├── api/                    # Main Rosetta API implementation
+│   ├── src/main/java/      # API controllers, services, mappers
+│   └── src/test/           # API tests
+├── yaci-indexer/           # Blockchain indexer module
+├── test-data-generator/    # Test data generation utility
+├── docker/                 # Docker configuration files
+├── docs/                   # Documentation (Docusaurus)
+└── pom.xml                # Parent POM
+```
+
+### Key Packages in API Module
+
+- `account/` - Account balance operations
+- `block/` - Block and transaction retrieval
+- `construction/` - Transaction building
+- `network/` - Network status and configuration
+- `mempool/` - Mempool operations
+
+## Making Contributions
+
+### Branch Naming Convention
+
+- `feature/description` - New features
+- `fix/description` - Bug fixes
+- `docs/description` - Documentation updates
+- `refactor/description` - Code refactoring
+- `test/description` - Test additions or fixes
+
+### Commit Message Format
+
+Follow the conventional commits specification:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types**:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Test additions or modifications
+- `chore`: Build process or auxiliary tool changes
+
+**Example**:
+```
+feat(api): add support for governance operations
+
+Implements the new Conway era governance operations including
+DRep delegation and voting operations.
+
+Closes #123
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Unit tests
+mvn test
+
+# Integration tests
+mvn verify -P integration-tests
+
+# Test with coverage
+mvn test jacoco:report
+```
+
+### Writing Tests
+
+- Extend `BaseSpringMvcSetup` for integration tests
+- Extend `BaseMapperSetup` for mapper tests
+- Use `@Nested` classes to group related tests
+- Use AssertJ for assertions
+
+**Example Test Structure**:
+```java
+@ExtendWith(MockitoExtension.class)
+class AccountServiceTest extends BaseSpringMvcSetup {
+    
+    @Nested
+    class GetBalance {
+        @Test
+        void shouldReturnCorrectBalance() {
+            // Given
+            var address = "addr1...";
+            
+            // When
+            var result = accountService.getBalance(address);
+            
+            // Then
+            assertThat(result)
+                .isNotNull()
+                .satisfies(balance -> {
+                    assertThat(balance.getValue()).isEqualTo("1000000");
+                });
+        }
+    }
+}
+```
+
+### Test Data
+
+- Place test data files in `src/test/resources/testdata/`
+- Use meaningful names for test data files
+- Document complex test scenarios
+
+## Pull Request Process
+
+1. **Update Your Fork**:
+   ```bash
+   git fetch upstream
+   git checkout main
+   git merge upstream/main
+   ```
+
+2. **Create a Feature Branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make Your Changes**:
+   - Write clean, documented code
+   - Add/update tests as needed
+   - Update documentation if applicable
+
+4. **Run Quality Checks**:
+   ```bash
+   # Format code
+   mvn spotless:apply
+   
+   # Run tests
+   mvn clean test
+   
+   # Check for common issues
+   mvn clean verify
+   ```
+
+5. **Commit Your Changes**:
+   ```bash
+   git add .
+   git commit -m "feat: add new feature"
+   ```
+
+6. **Push to Your Fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. **Create Pull Request**:
+   - Go to the original repository
+   - Click "New Pull Request"
+   - Select your fork and branch
+   - Fill in the PR template
+   - Link related issues
+
+### PR Requirements
+
+- [ ] Tests pass locally
+- [ ] Code follows project style guidelines
+- [ ] Documentation updated (if applicable)
+- [ ] Commit messages follow convention
+- [ ] PR description clearly explains changes
+- [ ] Related issues are linked
+
+## Code Style Guidelines
+
+### Java Code Style
+
+- Use **Lombok** annotations to reduce boilerplate
+- Use **MapStruct** for object mapping
+- Follow standard Java naming conventions
+- Maximum line length: 120 characters
+- Use `@Nullable` for optional parameters
+
+### Best Practices
+
+1. **Never modify generated code** - OpenAPI controllers are generated
+2. **Use dependency injection** - Avoid static methods where possible
+3. **Write testable code** - Keep methods focused and testable
+4. **Document complex logic** - Add JavaDoc for non-obvious code
+5. **Handle errors gracefully** - Use proper exception handling
+
+### Example Code Style
+
+```java
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class AccountService {
+    
+    private final AccountRepository repository;
+    private final AccountMapper mapper;
+    
+    /**
+     * Retrieves account balance for the given address.
+     * 
+     * @param address The Cardano address
+     * @return Account balance information
+     */
+    public AccountBalance getBalance(@Nullable String address) {
+        if (address == null) {
+            throw new InvalidAddressException("Address cannot be null");
+        }
+        
+        return repository.findByAddress(address)
+            .map(mapper::toDto)
+            .orElseThrow(() -> new AccountNotFoundException(address));
+    }
+}
+```
+
+## Reporting Issues
+
+### Before Creating an Issue
+
+1. Check [existing issues](https://github.com/cardano-foundation/cardano-rosetta-java/issues)
+2. Search [discussions](https://github.com/cardano-foundation/cardano-rosetta-java/discussions)
+3. Review the [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/intro)
+
+### Creating a Good Issue Report
+
+**Bug Reports** should include:
+- Clear, descriptive title
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- System information (OS, Java version, etc.)
+- Relevant logs or error messages
+
+**Feature Requests** should include:
+- Clear use case
+- Proposed solution
+- Alternative solutions considered
+- Impact on existing functionality
+
+### Issue Templates
+
+Use the provided issue templates when creating new issues:
+- 🐛 Bug Report
+- ✨ Feature Request
+- 📚 Documentation Update
+
+## Getting Help
+
+- **Discord**: [Join our community](https://discord.gg/cardanofoundation)
+- **GitHub Discussions**: Ask questions and share ideas
+- **Documentation**: [Project docs](https://cardano-foundation.github.io/cardano-rosetta-java/docs/intro)
+
+## Recognition
+
+Contributors will be recognized in:
+- Release notes
+- Project documentation
+- GitHub contributors page
+
+Thank you for contributing to Cardano Rosetta Java! Your efforts help make Cardano integration easier and more reliable for everyone.
\ No newline at end of file
diff --git a/README.md b/README.md
index 552d0ba61..1c39de48a 100644
--- a/README.md
+++ b/README.md
@@ -1,146 +1,264 @@
-[![Build](https://github.com/cardano-foundation/cardano-rosetta-java/actions/workflows/feature-mvn-build.yaml/badge.svg)](https://github.com/cardano-foundation/cardano-rosetta-java/actions/workflows/feature-mvn-build.yaml)
-[![License](https://img.shields.io:/github/license/cardano-foundation/cardano-rosetta-java?label=license)](https://github.com/cardano-foundation/cardano-rosetta-java/blob/master/LICENSE)
-![Discord](https://img.shields.io/discord/1022471509173882950)
-[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=cardano-foundation_cardano-rosetta-java&metric=coverage)](https://sonarcloud.io/summary/overall?id=cardano-foundation_cardano-rosetta-java)
+# Cardano Rosetta Java
+
+**High-performance Java implementation of the Mesh API (formerly Rosetta) for Cardano blockchain integration.**
+
+[![Build](https://img.shields.io/github/actions/workflow/status/cardano-foundation/cardano-rosetta-java/feature-mvn-build.yaml?label=build)](https://github.com/cardano-foundation/cardano-rosetta-java/actions/workflows/feature-mvn-build.yaml)
+[![Tests](https://img.shields.io/github/actions/workflow/status/cardano-foundation/cardano-rosetta-java/integration-test.yaml?label=tests)](https://github.com/cardano-foundation/cardano-rosetta-java/actions/workflows/integration-test.yaml)
+[![Release](https://img.shields.io/github/v/release/cardano-foundation/cardano-rosetta-java)](https://github.com/cardano-foundation/cardano-rosetta-java/releases/latest)
+[![Docker](https://img.shields.io/docker/pulls/cardanofoundation/cardano-rosetta-java)](https://hub.docker.com/r/cardanofoundation/cardano-rosetta-java)
+[![Discord](https://img.shields.io/discord/1022471509173882950?logo=discord)](https://discord.gg/cardanofoundation)
+[![License](https://img.shields.io:/github/license/cardano-foundation/cardano-rosetta-java)](https://github.com/cardano-foundation/cardano-rosetta-java/blob/master/LICENSE)
+
+[![Java](https://img.shields.io/badge/Java-24-orange)](https://openjdk.org/projects/jdk/24/)
+[![Mesh API](https://img.shields.io/badge/Mesh%20API-1.4.15-blue)](https://docs.cdp.coinbase.com/mesh/docs/welcome)
+[![Networks](https://img.shields.io/badge/Networks-Mainnet%20%7C%20Preprod%20%7C%20Preview-green)](https://cardano-foundation.github.io/cardano-rosetta-java/docs/intro)
+[![Docker Size](https://img.shields.io/docker/image-size/cardanofoundation/cardano-rosetta-java/latest?label=docker%20size)](https://hub.docker.com/r/cardanofoundation/cardano-rosetta-java)
+
+## Overview
+
+Cardano Rosetta Java provides a production-grade implementation of the [Mesh API specification](https://docs.cdp.coinbase.com/mesh/docs/welcome) (formerly Rosetta) for the Cardano blockchain. Built with Java and powered by [Yaci-Store](https://github.com/bloxbean/yaci-store), it offers significantly lower resource consumption compared to alternative implementations.
+
+### Architecture
+
+```mermaid
+graph LR
+    Client[Client]
+    
+    subgraph "Docker Compose Stack"
+        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
+```
 
-## What the project is about?
+### 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% (enabled by default)
+- **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.)
 
-This repository provides a lightweight java implementation of the [Rosetta API](https://github.com/coinbase/mesh-specifications). It uses [Yaci-Store](https://github.com/bloxbean/yaci-store) as an indexer
-to fetch the data from a Cardano node.
+## Quick Start
 
-This component consists of:
+<details>
+<summary><b>Preprod Testnet</b> (~3 hours sync time)</summary>
 
-- a full Cardano node
-- a Cardano Submit API
-- an indexer which stores data in Postgres
-- the Mesh (formerly Rosetta) API
+### Prerequisites
+- Docker and Docker Compose
+- 4+ CPU cores, 32GB RAM, 100GB storage
 
-This implementation follows the [Rosetta API](https://docs.cdp.coinbase.com/mesh/docs/api-reference/) specification and is compatible with the [Rosetta CLI](https://docs.cdp.coinbase.com/mesh/docs/mesh-cli/).
-It contains some extensions to fit the needs of the Cardano blockchain. These changes are documented in the [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/core-concepts/cardano-addons).
+### Steps
 
-## Documentation
+1. **Clone and launch**
+```bash
+git clone https://github.com/cardano-foundation/cardano-rosetta-java.git
+cd cardano-rosetta-java
 
-Detailed explanation to all components can be found in the [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/intro) of this repository.
-It includes explanations about the Architecture, how to build and run the components and explanations to environment variables.
+docker compose --env-file .env.docker-compose-preprod \
+  --env-file .env.docker-compose-profile-entry-level \
+  -f docker-compose.yaml up -d
+```
 
-## System requirements
+2. **Monitor sync progress**
+```bash
+# Check sync status
+curl -X POST http://localhost:8082/network/status \
+  -H "Content-Type: application/json" \
+  -d '{"network_identifier": {"blockchain": "cardano", "network": "preprod"}}'
 
-Since [Yaci-Store](https://github.com/bloxbean/yaci-store) is a comparatively lightweight indexer, the system requirements are lower than for other chain indexers. The following are the recommended system requirements for running this component:
+# View logs
+docker compose logs -f
+```
 
-- 4CPU Cores
-- 32GB RAM
-- ~1.3 TB total storage (node ~250 GB + Rosetta DB ~1 TB) — pruning disabled [default]
-- ~750 GB total storage (node ~250 GB + Rosetta DB ~500 GB) — pruning enabled
+</details>
 
-Better hardware will improve the performance of the indexer and the node, which will result in faster syncing times.
+<details>
+<summary><b>Mainnet</b> (48-72 hours sync time with Mithril)</summary>
 
-## Installation
+### Prerequisites
+- Docker and Docker Compose
+- 8+ CPU cores, 48GB RAM, 750GB storage (with pruning)
 
-By default this Cardano-node will sync the entire chain from Genesis.
-This will take up to 48-72 hours (dependening on the system resources).
+### Steps
 
-### Docker (build from source)
+1. **Clone and launch**
+```bash
+git clone https://github.com/cardano-foundation/cardano-rosetta-java.git
+cd cardano-rosetta-java
 
-If your user is not in the `docker` group you might have to execute these commands with `sudo`.
-The default config is focused on mainnet. If you want to test this on other Cardano netwoks (like `preview` or `preprod`) please adjust the `docker/.env.dockerfile` or read the documentation page on [Environment variables](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/env-vars) on other options and their default values.
+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**
 ```bash
-    git clone https://github.com/cardano-foundation/cardano-rosetta-java
-    cd cardano-rosetta-java
-    docker build -t rosetta-java -f ./docker/Dockerfile .
-    docker run --name rosetta -v {CUSTOM_MOUNT_PATH}:/node --env-file ./docker/.env.dockerfile --env-file ./docker/.env.docker-profile-mid-level -p 8082:8082 --shm-size=4g -d rosetta-java
+# Check sync status
+curl -X POST http://localhost:8082/network/status \
+  -H "Content-Type: application/json" \
+  -d '{"network_identifier": {"blockchain": "cardano", "network": "mainnet"}}'
 ```
 
-Detailed explanation can be found in the [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/docker).
+> **Note**: Mithril snapshots are used automatically to accelerate initial sync. Full sync times vary based on hardware and network conditions.
 
-Depending on using a snapshot feature or not, this will take X amount of time. You can follow along with the commands below. Your instance is ready when you see: `DONE`.
+</details>
 
-### Offline mode
+## System Requirements
 
-If you want to run rosetta-java in offline mode you need to set the `API_SPRING_PROFILES_ACTIVE` environment variable to `offline` in `./docker/.env.dockerfile`.
-This will disable the syncing of the node and won't start the db and the indexer.
-Default is `online`.
+Based on our [hardware profiles](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/hardware-profiles):
 
-**Useful commands:**
+| Profile | CPU | RAM | Storage* | Use Case |
+|---------|-----|-----|----------|----------|
+| **Entry-Level** | 4 cores | 32GB | 100GB (testnet) | Development & testing |
+| **Mid-Level** ⭐ | 8 cores | 48GB | 750GB | Production (recommended) |
+| **Advanced** | 16 cores | 94GB | 1TB+ | High-volume exchanges |
 
-- Following Docker container logs:
+*With UTXO pruning enabled (default). Add ~40% for full history.
 
-```bash
-    docker logs rosetta -f
-```
+## Installation
 
-- Access node logs:
+### Docker Compose (Recommended)
 
-```bash
-    docker exec rosetta tail -f /logs/node.log
-```
+See [Quick Start](#quick-start) above or the [installation documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/docker).
 
-- Access indexer logs:
+### Other Methods
 
-```bash
-    docker exec rosetta tail -f /logs/indexer.log
-```
+- **Pre-built images**: [DockerHub](https://hub.docker.com/r/cardanofoundation/cardano-rosetta-java)
+- **Build from source**: [Documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/development/build)
 
-- Interactive access to container:
+## Configuration
 
-```bash
-    docker exec -it rosetta bash # direct bash access within the container
+### 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` |
+| `API_PORT` | Mesh API port | `8082` |
 
-    # Useful commands within the container
-    cardano-cli query tip --mainnet # check node sync status
-    tail -f /logs/node.log # follow node logs
-    tail -f /logs/indexer.log # follow indexer logs
-```
+Full environment variable reference: [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/env-vars).
 
-### Docker (using pre-built image)
+### Spent UTXO Pruning
 
-For every Release we provide pre-built docker images stored in the DockerHub Repositories of the Cardano Foundation ([DockerHub](https://hub.docker.com/orgs/cardanofoundation/repositories))
-To start it use the following command:
+Pruning is **enabled by default** to optimize for high-performance exchange operations:
 
-```bash
-    docker run --name rosetta -v {CUSTOM_MOUNT_PATH}:/node --env-file ./docker/.env.dockerfile --env-file ./docker/.env.docker-profile-mid-level -p 8082:8082 --shm-size=4g -d cardanofoundation/cardano-rosetta-java:1.3.2
-```
+- **When enabled (default)**: Maintains current UTXO set and spent UTXOs within the safety margin (2,160 blocks/~12 hours), reducing storage by ~40% and improving query performance
+- **When disabled**: Functions as a full indexer maintaining complete historical data for all transactions and spent UTXOs
+
+For detailed configuration, see [pruning documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/advanced-configuration/pruning).
+
+## API Usage
 
-Changes to the configuration can be made by adjusting the `docker/.env.dockerfile` file. For more information on the environment variables, please refer to the [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/env-vars).
+<details>
+<summary><b>Common Operations</b></summary>
 
-If you want to use the `cardano-submit-api` you can additionally expose port `8090`. It can then be used to submit raw cbor transaction (API documentation here: [Link](https://input-output-hk.github.io/cardano-rest/submit-api/))
+### Check Network Status
+```bash
+curl -X POST http://localhost:8082/network/status \
+  -H "Content-Type: application/json" \
+  -d '{"network_identifier": {"blockchain": "cardano", "network": "mainnet"}}'
+```
 
+### Get Account Balance
 ```bash
-    docker run --name rosetta -v {CUSTOM_MOUNT_PATH}:/node --env-file ./docker/.env.dockerfile --env-file ./docker/.env.docker-profile-mid-level -p 8090:8090 -p 8082:8082 --shm-size=4g -d cardanofoundation/cardano-rosetta-java:1.3.2
+curl -X POST http://localhost:8082/account/balance \
+  -H "Content-Type: application/json" \
+  -d '{
+    "network_identifier": {"blockchain": "cardano", "network": "mainnet"},
+    "account_identifier": {"address": "addr1..."}
+  }'
 ```
 
-### Docker compose
+### Submit Transaction
+```bash
+curl -X POST http://localhost:8082/construction/submit \
+  -H "Content-Type: application/json" \
+  -d '{
+    "network_identifier": {"blockchain": "cardano", "network": "mainnet"},
+    "signed_transaction": "..."
+  }'
+```
 
-If needed we also provide all components needed to run Rosetta in a docker-compose file.
-This will start:
+</details>
 
-- Cardano-node
-- Cardano-Submit-API
-- Yaci-Store
-- Rosetta-API
-- Postgres
+## Operations
 
-### Entry level hardware profile
+<details>
+<summary><b>Monitoring & Troubleshooting</b></summary>
 
+### Health Checks
 ```bash
-   docker compose --env-file .env.docker-compose --env-file .env.docker-compose-profile-mid-level -f docker-compose.yaml up -d
+# Container status
+docker compose ps
+
+# Service logs
+docker compose logs -f api
+docker compose logs -f yaci-indexer
+docker compose logs -f cardano-node
 ```
 
-### A complete list of hardware profiles:
+### Common Issues
 
-```
-.env.docker-compose-profile-entry-level
-.env.docker-compose-profile-mid-level
-.env.docker-compose-profile-advanced-level
-```
+| 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 fail | Pruning enabled (expected behavior) | Check `oldest_block_identifier` in `/network/status` for queryable range |
 
-See the [hardware profiles documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/hardware-profiles) for a full list of hardware profiles and their configurations.
+</details>
 
-Further adjustments can be made by changing `.env.docker-compose` file. For more information on the environment variables, please refer to the [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/env-vars).
+## Documentation
 
----
+- [Full Documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/intro)
+- [Mesh API Reference](https://docs.cdp.coinbase.com/mesh/docs/api-reference)
+- [Cardano Specific API Additions](https://cardano-foundation.github.io/cardano-rosetta-java/docs/core-concepts/cardano-addons)
+- [Hardware Profiles](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/hardware-profiles)
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/cardano-foundation/cardano-rosetta-java/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/cardano-foundation/cardano-rosetta-java/discussions)
+- **Discord**: [Cardano Foundation Discord](https://discord.gg/arhwSrTsSj)
+
+## Contributing
 
-Thanks for visiting us and enjoy :heart:!
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+[Apache License 2.0](LICENSE)
+
+---
 
+Built with ❤️ by the [Cardano Foundation](https://cardanofoundation.org)
\ No newline at end of file

From 0288cee02ee72cbe4f94639d31a838336ef2940f Mon Sep 17 00:00:00 2001
From: Lincon Vidal <lincon.vidal@cardanofoundation.org>
Date: Tue, 16 Sep 2025 15:20:47 -0300
Subject: [PATCH 2/6] docs: update resource requirements and pruning
 configuration in documentation

- Revised README.md to clarify resource requirements for different hardware profiles, including updated storage needs for pruning enabled and disabled scenarios.
- Enhanced documentation on pruning configuration, specifying default values and safety margins for spent UTXO pruning.
- Updated environment variable documentation to reflect changes in default settings for pruning options.
---
 README.md                                   | 24 ++++++++++++---------
 docs/docs/advanced-configuration/pruning.md | 20 ++++++++---------
 docs/docs/install-and-deploy/env-vars.md    |  8 +++----
 docs/docs/intro.md                          |  4 ++--
 4 files changed, 30 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 1c39de48a..7f9483d69 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ Cardano Rosetta Java provides a production-grade implementation of the [Mesh API
 graph LR
     Client[Client]
     
-    subgraph "Docker Compose Stack"
+    subgraph "Core Components"
         API[rosetta-api<br/>:8082]
         Indexer[yaci-indexer<br/>:9095]
         DB[(postgres<br/>:5432)]
@@ -72,7 +72,8 @@ graph LR
 
 ### Prerequisites
 - Docker and Docker Compose
-- 4+ CPU cores, 32GB RAM, 100GB storage
+- 4+ CPU cores, 32GB RAM
+- 100GB storage (pruning enabled) or 140GB (pruning disabled)
 
 ### Steps
 
@@ -104,7 +105,8 @@ docker compose logs -f
 
 ### Prerequisites
 - Docker and Docker Compose
-- 8+ CPU cores, 48GB RAM, 750GB storage (with pruning)
+- 8+ CPU cores, 48GB RAM
+- 750GB storage (pruning enabled) or 1.3TB (pruning disabled)
 
 ### Steps
 
@@ -134,13 +136,13 @@ curl -X POST http://localhost:8082/network/status \
 
 Based on our [hardware profiles](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/hardware-profiles):
 
-| Profile | CPU | RAM | Storage* | Use Case |
-|---------|-----|-----|----------|----------|
-| **Entry-Level** | 4 cores | 32GB | 100GB (testnet) | Development & testing |
-| **Mid-Level** ⭐ | 8 cores | 48GB | 750GB | Production (recommended) |
-| **Advanced** | 16 cores | 94GB | 1TB+ | High-volume exchanges |
+| 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 |
 
-*With UTXO pruning enabled (default). Add ~40% for full history.
+*Pruning enabled by default - reduces storage by ~40% while maintaining current UTXO set and recent history (configurable safety margin, default: 129,600 blocks/~30 days).
 
 ## Installation
 
@@ -162,6 +164,7 @@ See [Quick Start](#quick-start) above or the [installation documentation](https:
 | `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` |
 
 Full environment variable reference: [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/env-vars).
@@ -170,8 +173,9 @@ Full environment variable reference: [documentation](https://cardano-foundation.
 
 Pruning is **enabled by default** to optimize for high-performance exchange operations:
 
-- **When enabled (default)**: Maintains current UTXO set and spent UTXOs within the safety margin (2,160 blocks/~12 hours), reducing storage by ~40% and improving query performance
+- **When enabled (default)**: Maintains current UTXO set and spent UTXOs within the configurable safety margin (default: 129,600 blocks/~30 days), reducing storage by ~40% and improving query performance
 - **When disabled**: Functions as a full indexer maintaining complete historical data for all transactions and spent UTXOs
+- **Safety margin**: Configurable via `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` (default: 129600)
 
 For detailed configuration, see [pruning documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/advanced-configuration/pruning).
 
diff --git a/docs/docs/advanced-configuration/pruning.md b/docs/docs/advanced-configuration/pruning.md
index cda4e23b1..7ee917e25 100644
--- a/docs/docs/advanced-configuration/pruning.md
+++ b/docs/docs/advanced-configuration/pruning.md
@@ -22,7 +22,7 @@ When enabled, the pruning process operates as follows:
 
 1.  New UTXOs are indexed as transactions occur.
 2.  UTXOs are marked as spent when consumed in subsequent transactions.
-3.  A background job periodically permanently deletes spent UTXOs that are older than a configurable safety margin (default: 2,160 blocks, ~12 hours on mainnet). This buffer safeguards data integrity against chain rollbacks within Cardano's finality window.
+3.  A background job periodically permanently deletes spent UTXOs that are older than a configurable safety margin (default: 129,600 blocks, ~30 days on mainnet). This buffer safeguards data integrity against chain rollbacks within Cardano's finality window.
 
 **Impact Summary:**
 | Aspect | Effect |
@@ -34,7 +34,7 @@ When enabled, the pruning process operates as follows:
 
 ## Impact on Rosetta API Endpoints
 
-Spent UTXO pruning affects Rosetta API endpoints differently based on their reliance on historical transaction data. The table below summarizes the impact. Note that "Recent" refers to data within the safety margin (default ~12 hours).
+Spent UTXO pruning affects Rosetta API endpoints differently based on their reliance on historical transaction data. The table below summarizes the impact. Note that "Recent" refers to data within the safety margin (default ~30 days).
 
 :::info Oldest Block Identifier
 When pruning is enabled, the `/network/status` endpoint includes an additional `oldest_block_identifier` object in its response. This identifier corresponds to the latest fully queryable block with complete data. Below this block index, blocks might have missing data due to pruning, making historical queries unreliable.
@@ -89,24 +89,24 @@ Spent UTXO pruning is configured via environment variables, typically set in you
 # --- Spent UTXO Pruning Configuration ---
 
 # Enable or disable spent UTXO pruning.
-# Default: false (Pruning is disabled by default)
-# To enable, set to: true
+# Default: true (Pruning is enabled by default)
+# To disable, set to: false
 REMOVE_SPENT_UTXOS=true
 
 # Safety margin: Number of recent blocks for which spent UTXOs are retained.
-# Default: 2160 (approximately 12 hours of blocks on mainnet)
+# Default: 129600 (approximately 30 days of blocks on mainnet)
 # This value balances safety for rollbacks against storage savings.
-# Example: To keep ~24 hours of spent UTXOs, set to 4320.
+# Example: To keep ~7 days of spent UTXOs, set to 30240.
 # Note: Larger REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT values provide longer historical query support
 # but use more disk space and delay the realization of storage benefits.
-REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=2160
+REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=129600
 ```
 
 :::note Configuration Guidelines
 
-- Start with the default settings (`REMOVE_SPENT_UTXOS=false` keeps pruning off).
-- The provided defaults (`REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=2160`) offer ~12 h of rollback safety on mainnet.
-- Increase `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` if you need a longer historical query window; decrease it for more aggressive space savings.
+- Default settings have pruning enabled (`REMOVE_SPENT_UTXOS=true`) for optimal storage efficiency.
+- The provided defaults (`REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=129600`) offer ~30 days of rollback safety on mainnet.
+- Decrease `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` for more aggressive space savings (e.g., 2160 for ~12 hours); increase it if you need a longer historical query window.
   :::
 
 ## Migration and Operational Notes
diff --git a/docs/docs/install-and-deploy/env-vars.md b/docs/docs/install-and-deploy/env-vars.md
index 66346c54c..9e6856793 100644
--- a/docs/docs/install-and-deploy/env-vars.md
+++ b/docs/docs/install-and-deploy/env-vars.md
@@ -47,8 +47,8 @@ Within root folder of the project there are example `.env` files, which can be c
 | `GENESIS_ALONZO_PATH`                         | Genesis file path                                                     | ./config/mainnet/alonzo-genesis.json   | added in release 1.0.0  |
 | `GENESIS_CONWAY_PATH`                         | Genesis file path                                                     | ./config/mainnet/conway-genesis.json   | added in release 1.0.0  |
 | `INDEXER_DOCKER_IMAGE_TAG`                    | Yaci indexer Docker version                                           | main                                   | added in release 1.0.0  |
-| `REMOVE_SPENT_UTXOS`                          | If pruning should be enabled                                          | false                                  | added in release 1.0.0  |
-| `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT`  | Number of safe blocks to keep in the store                            | 2160                                   | added in release 1.2.4  |
+| `REMOVE_SPENT_UTXOS`                          | If pruning should be enabled                                          | true                                   | added in release 1.0.0  |
+| `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT`  | Number of safe blocks to keep in the store (~30 days)                | 129600                                 | added in release 1.2.4  |
 | `YACI_SPRING_PROFILES`                        | Yaci indexer spring profile                                           | postgres                               | added in release 1.0.0  |
 | `DEVKIT_ENABLED`                              | Devkit enabled                                                        | false                                  | added in release 1.0.0  |
 | `LOG`                                         | Log level                                                             | ERROR                                  | added in release 1.0.0  |
@@ -93,7 +93,7 @@ The following environment variables were available in previous versions but are
 
 | Variable              | Description                                                     | Default | Notes                                                                                         |
 |-----------------------|-----------------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------|
-| `PRUNING_ENABLED`     | Enable spent UTXO pruning to reduce storage requirements        | false   | available in releases 1.0.0 - 1.2.8, replaced by `REMOVE_SPENT_UTXOS`                         |
-| `PRUNING_SAFE_BLOCKS` | Number of recent blocks to keep spent UTXOs for (safety margin) | 2160    | available in releases 1.2.4 - 1.2.8, replaced by `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` |
+| `PRUNING_ENABLED`     | Enable spent UTXO pruning to reduce storage requirements        | false   | available in releases 1.0.0 - 1.2.8, replaced by `REMOVE_SPENT_UTXOS` (now defaults to true)  |
+| `PRUNING_SAFE_BLOCKS` | Number of recent blocks to keep spent UTXOs for (safety margin) | 2160    | available in releases 1.2.4 - 1.2.8, replaced by `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` (now defaults to 129600) |
 | `PRUNING_INTERVAL`    | Interval in seconds between pruning cleanup jobs                | 600     | available in releases 1.2.4 - 1.2.8, no longer configurable                                   |
 | `LIMIT`               | Search limit                                                    | 100     | available in releases 1.0.0 - 1.3.0, no longer configurable, replaced by `SEARCH_LIMIT`       |
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
index f88ebac8c..0c505934b 100644
--- a/docs/docs/intro.md
+++ b/docs/docs/intro.md
@@ -27,8 +27,8 @@ Running Cardano Rosetta Java requires the following minimum resources:
 | :---------- | :------------------------------------------------ | :-------------------------- |
 | **CPU**     | 4 Cores                                           |                             |
 | **RAM**     | 32 GB                                             |                             |
-| **Storage** | ~1.3 TB total (node ~250 GB + Rosetta DB ~1 TB)   | Spent UTXO pruning disabled |
-|             | ~750 GB total (node ~250 GB + Rosetta DB ~500 GB) | Spent UTXO pruning enabled  |
+| **Storage** | ~750 GB total (node ~250 GB + Rosetta DB ~500 GB) | Spent UTXO pruning enabled (default) |
+|             | ~1.3 TB total (node ~250 GB + Rosetta DB ~1 TB)   | Spent UTXO pruning disabled |
 
 :::tip Performance Note
 Better hardware resources (more CPU cores, RAM) will improve indexer and node performance, resulting in faster chain synchronization and better API response times.

From 260b8658c6b0c8a2652fda0b0182ae39af53241f Mon Sep 17 00:00:00 2001
From: Lincon Vidal <lincon.vidal@cardanofoundation.org>
Date: Thu, 18 Sep 2025 15:22:37 -0300
Subject: [PATCH 3/6] docs: update README and Docker documentation for
 environment management

- Enhanced README.md to clarify log viewing instructions and added commands for merging environment files to avoid warnings.
- Updated Docker documentation to include tips for managing environment files and emphasized the deprecation of the single Docker image deployment in favor of Docker Compose for better modularity and resource management.
---
 README.md                              |  8 +++-
 docs/docs/install-and-deploy/docker.md | 57 +++++++++++++++++++++-----
 2 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 7f9483d69..edb87b71d 100644
--- a/README.md
+++ b/README.md
@@ -94,7 +94,8 @@ curl -X POST http://localhost:8082/network/status \
   -H "Content-Type: application/json" \
   -d '{"network_identifier": {"blockchain": "cardano", "network": "preprod"}}'
 
-# View logs
+# View logs (merge env files to avoid warnings)
+cat .env.docker-compose-preprod .env.docker-compose-profile-entry-level > .env
 docker compose logs -f
 ```
 
@@ -126,6 +127,10 @@ docker compose --env-file .env.docker-compose \
 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.
@@ -153,6 +158,7 @@ See [Quick Start](#quick-start) above or the [installation documentation](https:
 ### Other Methods
 
 - **Pre-built images**: [DockerHub](https://hub.docker.com/r/cardanofoundation/cardano-rosetta-java)
+  > ⚠️ **Note**: The single Docker image deployment (cardanofoundation/cardano-rosetta-java) is deprecated. We strongly recommend using Docker Compose deployment for better modularity, resource management, and maintenance.
 - **Build from source**: [Documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/development/build)
 
 ## Configuration
diff --git a/docs/docs/install-and-deploy/docker.md b/docs/docs/install-and-deploy/docker.md
index ca7fa7bfd..66bd37819 100644
--- a/docs/docs/install-and-deploy/docker.md
+++ b/docs/docs/install-and-deploy/docker.md
@@ -44,6 +44,21 @@ docker compose --env-file .env.docker-compose \
   -f docker-compose.yaml up -d
 ```
 
+:::tip Managing Environment Files
+To avoid environment variable warnings when running `docker compose` commands later (like `docker compose logs`), you can merge the environment files:
+```bash
+# For mainnet with mid-level profile:
+cat .env.docker-compose .env.docker-compose-profile-mid-level > .env
+
+# For preprod with entry-level profile:
+cat .env.docker-compose-preprod .env.docker-compose-profile-entry-level > .env
+
+# Now you can run commands without warnings:
+docker compose ps
+docker compose logs -f
+```
+:::
+
 :::note
 The first time you run the command, it will take significant time to build the cardano-node.
 On subsequent runs, it will use the cached version.
@@ -68,9 +83,21 @@ Mithril provides cryptographically certified blockchain snapshots for multiple C
 :::
 
   </TabItem>
-  <TabItem value="prebuilt" label="Pre-built Docker Image">
+  <TabItem value="prebuilt" label="Pre-built Docker Image (Deprecated)">
+
+### Using Pre-built Docker Image (Deprecated)
+
+:::danger Deprecated Feature
+⚠️ **The single Docker image deployment is deprecated and not recommended for production use.**
 
-### Using Pre-built Docker Image
+This method bundles all components (cardano-node, indexer, API, and PostgreSQL) into a single container, which:
+- Makes resource management difficult
+- Complicates debugging and maintenance
+- Prevents independent component scaling
+- Is less reliable for production workloads
+
+**We strongly recommend using the Docker Compose deployment method instead**, which offers better modularity, resource management, and maintainability.
+:::
 
 For every release, pre-built docker images are available on [DockerHub](https://hub.docker.com/orgs/cardanofoundation/repositories):
 
@@ -100,9 +127,13 @@ API documentation is available [here](https://input-output-hk.github.io/cardano-
 :::
 
   </TabItem>
-  <TabItem value="source" label="Build from Source">
+  <TabItem value="source" label="Build from Source (Single Image)">
 
-### Building Docker Image from Source
+### Building Docker Image from Source (Single Container)
+
+:::warning Deprecated Approach
+This builds the deprecated single Docker image that bundles all components together. For production deployments, use the Docker Compose method which builds and manages components separately.
+:::
 
 ```bash
 git clone https://github.com/cardano-foundation/cardano-rosetta-java
@@ -188,13 +219,14 @@ For information about running in online mode (default) or offline mode (for air-
   <TabItem value="logs" label="Viewing Logs" default>
 
 ```bash
-# Follow Docker container logs
-docker logs rosetta -f
+# For Docker Compose deployments:
+docker compose logs -f api
+docker compose logs -f yaci-indexer
+docker compose logs -f cardano-node
 
-# Access node logs
+# For single container deployments (deprecated):
+docker logs rosetta -f
 docker exec rosetta tail -f /logs/node.log
-
-# Access indexer logs
 docker exec rosetta tail -f /logs/indexer.log
 ```
 
@@ -202,7 +234,12 @@ docker exec rosetta tail -f /logs/indexer.log
   <TabItem value="interactive" label="Interactive Shell">
 
 ```bash
-# Get interactive bash shell
+# For Docker Compose deployments:
+docker exec -it cardano-rosetta-java-cardano-node-1 bash
+docker exec -it cardano-rosetta-java-api-1 bash
+docker exec -it cardano-rosetta-java-yaci-indexer-1 bash
+
+# For single container deployments (deprecated):
 docker exec -it rosetta bash
 
 # Useful commands within the container

From fb39a9efae3313ebc42675d47125c8eba9980d30 Mon Sep 17 00:00:00 2001
From: Lincon Vidal <lincon.vidal@cardanofoundation.org>
Date: Thu, 18 Sep 2025 16:45:00 -0300
Subject: [PATCH 4/6] docs: cleanup tags, highlight pruning info and other
 cosmetics

- Revised README.md to clarify that Spent UTXO pruning is enabled by default starting from v1.4.0.
- Enhanced warnings about the deprecation of the single Docker image deployment.
---
 README.md                              | 72 +++++++++++---------------
 docs/docs/install-and-deploy/docker.md |  2 +-
 2 files changed, 31 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index edb87b71d..c12a7f9f9 100644
--- a/README.md
+++ b/README.md
@@ -3,16 +3,11 @@
 **High-performance Java implementation of the Mesh API (formerly Rosetta) for Cardano blockchain integration.**
 
 [![Build](https://img.shields.io/github/actions/workflow/status/cardano-foundation/cardano-rosetta-java/feature-mvn-build.yaml?label=build)](https://github.com/cardano-foundation/cardano-rosetta-java/actions/workflows/feature-mvn-build.yaml)
-[![Tests](https://img.shields.io/github/actions/workflow/status/cardano-foundation/cardano-rosetta-java/integration-test.yaml?label=tests)](https://github.com/cardano-foundation/cardano-rosetta-java/actions/workflows/integration-test.yaml)
-[![Release](https://img.shields.io/github/v/release/cardano-foundation/cardano-rosetta-java)](https://github.com/cardano-foundation/cardano-rosetta-java/releases/latest)
-[![Docker](https://img.shields.io/docker/pulls/cardanofoundation/cardano-rosetta-java)](https://hub.docker.com/r/cardanofoundation/cardano-rosetta-java)
-[![Discord](https://img.shields.io/discord/1022471509173882950?logo=discord)](https://discord.gg/cardanofoundation)
-[![License](https://img.shields.io:/github/license/cardano-foundation/cardano-rosetta-java)](https://github.com/cardano-foundation/cardano-rosetta-java/blob/master/LICENSE)
-
-[![Java](https://img.shields.io/badge/Java-24-orange)](https://openjdk.org/projects/jdk/24/)
+[![Tests](https://img.shields.io/github/actions/workflow/status/cardano-foundation/cardano-rosetta-java/integration-test.yaml?label=integration)](https://github.com/cardano-foundation/cardano-rosetta-java/actions/workflows/integration-test.yaml)
+[![Latest Release](https://img.shields.io/github/v/release/cardano-foundation/cardano-rosetta-java)](https://github.com/cardano-foundation/cardano-rosetta-java/releases/latest)
+[![Java](https://img.shields.io/badge/Java-24-blue)](https://openjdk.org/projects/jdk/24/)
 [![Mesh API](https://img.shields.io/badge/Mesh%20API-1.4.15-blue)](https://docs.cdp.coinbase.com/mesh/docs/welcome)
-[![Networks](https://img.shields.io/badge/Networks-Mainnet%20%7C%20Preprod%20%7C%20Preview-green)](https://cardano-foundation.github.io/cardano-rosetta-java/docs/intro)
-[![Docker Size](https://img.shields.io/docker/image-size/cardanofoundation/cardano-rosetta-java/latest?label=docker%20size)](https://hub.docker.com/r/cardanofoundation/cardano-rosetta-java)
+[![License](https://img.shields.io:/github/license/cardano-foundation/cardano-rosetta-java)](https://github.com/cardano-foundation/cardano-rosetta-java/blob/master/LICENSE)
 
 ## Overview
 
@@ -59,7 +54,7 @@ graph LR
 
 - **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% (enabled by default)
+- **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)
@@ -67,6 +62,14 @@ graph LR
 
 ## Quick Start
 
+> [!IMPORTANT]
+> Starting from v1.4.0, [Spent UTXO Pruning](https://cardano-foundation.github.io/cardano-rosetta-java/docs/advanced-configuration/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.
+
 <details>
 <summary><b>Preprod Testnet</b> (~3 hours sync time)</summary>
 
@@ -132,23 +135,21 @@ curl -X POST http://localhost:8082/network/status \
 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.
-
 </details>
 
+> [!NOTE]
+> [Mithril snapshots](https://mithril.network/doc/) are used automatically to accelerate initial sync. Full sync times vary based on hardware and network conditions.
+
 ## System Requirements
 
 Based on our [hardware profiles](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/hardware-profiles):
 
-| Profile | CPU | RAM | Storage (Pruning Enabled)* | Storage (Pruning Disabled) | Use Case |
-|---------|-----|-----|----------------------------|----------------------------|----------|
+| 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 |
 
-*Pruning enabled by default - reduces storage by ~40% while maintaining current UTXO set and recent history (configurable safety margin, default: 129,600 blocks/~30 days).
-
 ## Installation
 
 ### Docker Compose (Recommended)
@@ -157,8 +158,11 @@ See [Quick Start](#quick-start) above or the [installation documentation](https:
 
 ### Other Methods
 
-- **Pre-built images**: [DockerHub](https://hub.docker.com/r/cardanofoundation/cardano-rosetta-java)
-  > ⚠️ **Note**: The single Docker image deployment (cardanofoundation/cardano-rosetta-java) is deprecated. We strongly recommend using Docker Compose deployment for better modularity, resource management, and maintenance.
+
+> [!WARNING]
+> The single Docker image deployment is deprecated. We strongly recommend using Docker Compose deployment for better modularity, resource management, and maintenance.
+
+- **Pre-built all-in-one images**: [DockerHub](https://hub.docker.com/r/cardanofoundation/cardano-rosetta-java)
 - **Build from source**: [Documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/development/build)
 
 ## Configuration
@@ -173,19 +177,9 @@ See [Quick Start](#quick-start) above or the [installation documentation](https:
 | `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` | Safety margin for pruning (in blocks) | `129600` (~30 days) |
 | `API_PORT` | Mesh API port | `8082` |
 
-Full environment variable reference: [documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/env-vars).
-
-### Spent UTXO Pruning
-
-Pruning is **enabled by default** to optimize for high-performance exchange operations:
-
-- **When enabled (default)**: Maintains current UTXO set and spent UTXOs within the configurable safety margin (default: 129,600 blocks/~30 days), reducing storage by ~40% and improving query performance
-- **When disabled**: Functions as a full indexer maintaining complete historical data for all transactions and spent UTXOs
-- **Safety margin**: Configurable via `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` (default: 129600)
+Check [environment variable reference](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/env-vars) for details.
 
-For detailed configuration, see [pruning documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/advanced-configuration/pruning).
-
-## API Usage
+## API Usage & Operations
 
 <details>
 <summary><b>Common Operations</b></summary>
@@ -219,8 +213,6 @@ curl -X POST http://localhost:8082/construction/submit \
 
 </details>
 
-## Operations
-
 <details>
 <summary><b>Monitoring & Troubleshooting</b></summary>
 
@@ -244,22 +236,18 @@ docker compose logs -f cardano-node
 | 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 fail | Pruning enabled (expected behavior) | Check `oldest_block_identifier` in `/network/status` for queryable range |
+| Historical queries return incomplete data | Pruning enabled (by design) | Check `oldest_block_identifier` in `/network/status` for fully queryable range |
 
 </details>
 
-## Documentation
+## Documentation & Support
 
 - [Full Documentation](https://cardano-foundation.github.io/cardano-rosetta-java/docs/intro)
 - [Mesh API Reference](https://docs.cdp.coinbase.com/mesh/docs/api-reference)
 - [Cardano Specific API Additions](https://cardano-foundation.github.io/cardano-rosetta-java/docs/core-concepts/cardano-addons)
 - [Hardware Profiles](https://cardano-foundation.github.io/cardano-rosetta-java/docs/install-and-deploy/hardware-profiles)
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/cardano-foundation/cardano-rosetta-java/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/cardano-foundation/cardano-rosetta-java/discussions)
-- **Discord**: [Cardano Foundation Discord](https://discord.gg/arhwSrTsSj)
+- [GitHub Issues](https://github.com/cardano-foundation/cardano-rosetta-java/issues)
+- [GitHub Discussions](https://github.com/cardano-foundation/cardano-rosetta-java/discussions)
 
 ## Contributing
 
@@ -271,4 +259,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 ---
 
-Built with ❤️ by the [Cardano Foundation](https://cardanofoundation.org)
\ No newline at end of file
+Built with ❤️ by the [Cardano Foundation](https://cardanofoundation.org)
diff --git a/docs/docs/install-and-deploy/docker.md b/docs/docs/install-and-deploy/docker.md
index 66bd37819..ad05f4129 100644
--- a/docs/docs/install-and-deploy/docker.md
+++ b/docs/docs/install-and-deploy/docker.md
@@ -14,7 +14,7 @@ Before you begin, ensure you have the following installed:
 
 - Docker
 - Docker Compose
-- Java 21
+- Java 24
 - For integration tests: Node 14+
 
 ## Deployment Options

From 3e32e9eeab3755c03b9dded6b4748fcaa60be340 Mon Sep 17 00:00:00 2001
From: Lincon Vidal <lincon.vidal@cardanofoundation.org>
Date: Thu, 18 Sep 2025 17:18:20 -0300
Subject: [PATCH 5/6] docs: enhance multi-assets guide with account balance and
 UTXO queries

- Updated the multi-assets documentation to clarify the usage of `/account/balance` and `/account/coins` endpoints for querying account balances and UTXOs.
- Added detailed request and response examples for both endpoints, including information on querying with stake addresses and known issues.
- Improved structure with tabs for better navigation and clarity.
---
 docs/docs/user-guides/multi-assets.md | 62 ++++++++++++++++++++++++---
 1 file changed, 57 insertions(+), 5 deletions(-)

diff --git a/docs/docs/user-guides/multi-assets.md b/docs/docs/user-guides/multi-assets.md
index 3944c62e0..e08a9af98 100644
--- a/docs/docs/user-guides/multi-assets.md
+++ b/docs/docs/user-guides/multi-assets.md
@@ -116,18 +116,38 @@ The Rosetta representation doesn't explicitly label these as mint/burn operation
   </TabItem>
 </Tabs>
 
-## Account Balance Queries
+## Account Balance and UTXO Queries
 
-When querying account balances using `/account/balance`, the response will include both ADA and any native tokens owned by the address.
+Cardano Rosetta provides two separate endpoints for querying account information:
+
+<Tabs>
+  <TabItem value="balance" label="/account/balance" default>
+
+### Account Balance
+
+The `/account/balance` endpoint returns the **aggregated balance** of all ADA and native tokens owned by an address.
 
 :::info Note on Stake Addresses
-When the `/account/balance` endpoint is queried with a stake address (also known as a reward address), the response will include the available rewards that can be withdrawn from the stake address.
+When queried with a stake address (reward address), the response includes available rewards that can be withdrawn.
 
-This means the API provides a consolidated view of both spendable funds (from payment addresses) and claimable rewards when a stake address is used in the query.
+**Known Issue:** Historical queries for stake address rewards currently return the current reward value instead of the historical value at the specified block. See [Issue #590](https://github.com/cardano-foundation/cardano-rosetta-java/issues/590).
 :::
 
+**Request:**
+```json
+{
+  "network_identifier": {"blockchain": "cardano", "network": "mainnet"},
+  "account_identifier": {"address": "addr1..."}
+}
+```
+
+**Response:**
 ```json
 {
+  "block_identifier": {
+    "index": 10453789,
+    "hash": "6e9e89632bc5c72030d3a486647e889c48d63e4da0643191b13566ad816d2d57"
+  },
   "balances": [
     {
       "value": "71103107",
@@ -146,7 +166,32 @@ This means the API provides a consolidated view of both spendable funds (from pa
         }
       }
     }
-  ],
+  ]
+}
+```
+
+  </TabItem>
+  <TabItem value="coins" label="/account/coins">
+
+### Account UTXOs
+
+The `/account/coins` endpoint returns the **individual UTXOs** (unspent transaction outputs) owned by an address, including any native tokens attached to each UTXO.
+
+**Request:**
+```json
+{
+  "network_identifier": {"blockchain": "cardano", "network": "mainnet"},
+  "account_identifier": {"address": "addr1..."}
+}
+```
+
+**Response:**
+```json
+{
+  "block_identifier": {
+    "index": 10453789,
+    "hash": "6e9e89632bc5c72030d3a486647e889c48d63e4da0643191b13566ad816d2d57"
+  },
   "coins": [
     {
       "coin_identifier": {
@@ -179,3 +224,10 @@ This means the API provides a consolidated view of both spendable funds (from pa
   ]
 }
 ```
+
+:::tip
+Native tokens in Cardano are always attached to UTXOs containing ADA. The `metadata` field shows which tokens are contained in each specific UTXO.
+:::
+
+  </TabItem>
+</Tabs>

From f7b560ea2ad801cb17c20db1425db9974a1fc7d7 Mon Sep 17 00:00:00 2001
From: Kartiiyer12 <kartikiyer2020@gmail.com>
Date: Thu, 25 Sep 2025 14:07:06 +0200
Subject: [PATCH 6/6] docs: add offline operations deployment docs and FULL
 VACCUM commands after pruning to reclaim file size

---
 docs/docs/advanced-configuration/pruning.md | 26 ++++++++++++++++++++-
 docs/docs/core-concepts/operation-modes.md  | 25 ++++++++++++++++----
 docs/docs/install-and-deploy/docker.md      |  3 +++
 3 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/docs/docs/advanced-configuration/pruning.md b/docs/docs/advanced-configuration/pruning.md
index 7ee917e25..0c0176fea 100644
--- a/docs/docs/advanced-configuration/pruning.md
+++ b/docs/docs/advanced-configuration/pruning.md
@@ -132,7 +132,31 @@ The resynchronization process rebuilds the indexer database from your existing C
 
 This is necessary in two main scenarios:
 
-- **To reclaim disk space**: When you enable pruning on an existing instance, a resync will clear out historically spent UTXOs.
+- **To reclaim disk space**: When you enable pruning on an existing instance, a resync will clear out historically spent UTXOs. However, to actually reduce the file size on disk after `REMOVE_SPENT_UTXOS` is enabled and the indexer has fully synced, you must manually reclaim the space using PostgreSQL's VACUUM FULL command on the affected tables:
+
+  ```bash
+  # Connect to the PostgreSQL database
+  docker exec -e PGPASSWORD="<password>" -it <postgres-container-name> psql -U <username> -d rosetta-java
+
+  # set schema
+  set search_path to mainnet;
+
+  # Run VACUUM FULL on the tables that store UTXO data
+  VACUUM FULL tx_input;
+  VACUUM FULL address_utxo;
+  ```
+
+    :::warning Database Maintenance Required
+    The VACUUM FULL operation requires an exclusive lock on the tables and can take significant time to complete.   Plan for potential downtime during this maintenance operation. In addition, sufficient free disk space must be available, since VACUUM FULL rewrites each table by creating a new copy before replacing the old one. For example, in this case you would need approximately 400 GB of free space to complete the operation. The process will:
+
+    - **Reclaim disk space**: Remove the gaps left by deleted spent UTXOs
+    - **Reorganize table data**: Compact the remaining data for better performance
+    - **Require exclusive access**: Block all other operations on these tables during execution
+    :::
+
+    :::tip Alternative Approach
+    If you prefer to avoid the VACUUM FULL maintenance window, performing a complete indexer resynchronization (as described above) will achieve the same disk space reclamation while rebuilding the database from scratch with the new pruning configuration.
+    :::
 - **To restore full history**: When you disable pruning, a resync will rebuild the complete transaction history that was previously pruned away.
 
 :::tip Quick Resynchronization Steps
diff --git a/docs/docs/core-concepts/operation-modes.md b/docs/docs/core-concepts/operation-modes.md
index e417c30ad..ed8fe6ab0 100644
--- a/docs/docs/core-concepts/operation-modes.md
+++ b/docs/docs/core-concepts/operation-modes.md
@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
 <Tabs>
   <TabItem value="online" label="Online Mode" default>
 
-## Online Mode
+
 
 In online mode, the system connects to the Cardano network, synchronizes the blockchain, and provides real-time access to blockchain data. This is the default mode and requires a connection to the Cardano network.
 
@@ -29,20 +29,35 @@ This mode is used for blockchain synchronization, transaction broadcasting, and
   </TabItem>
   <TabItem value="offline" label="Offline Mode">
 
-## Offline Mode
+
 
 In offline mode, the system operates without connecting to the Cardano network. The Cardano Node, YACI Indexer, and PostgreSQL components are disabled, and only the Rosetta API is active.
 
 Offline mode is useful for transaction construction and signing in air-gapped environments or security-critical applications. This mode allows you to create and sign transactions without broadcasting them to the network, which is particularly important for cold wallet solutions and high-security setups.
 
 :::tip Enabling Offline Mode
-To enable offline mode, set the `API_SPRING_PROFILES_ACTIVE` environment variable to `offline` in the configuration file:
-
+To enable offline mode, set the `API_SPRING_PROFILES_ACTIVE` and `TOKEN_REGISTRY_ENABLED` as below:
 ```bash
 API_SPRING_PROFILES_ACTIVE=offline
+TOKEN_REGISTRY_ENABLED=false
 ```
-
 :::
 
+#### Deployment Option
+
+##### Using Docker Compose
+
+1. Clone the repository
+```bash
+git clone https://github.com/cardano-foundation/cardano-rosetta-java.git
+```
+2. Use the provided environment files:
+   - The default configuration is in `.env.docker-compose`
+
+```bash
+docker compose --env-file .env.docker-compose \
+  -f docker-compose-offline.yaml up -d
+```
+
   </TabItem>
 </Tabs>
diff --git a/docs/docs/install-and-deploy/docker.md b/docs/docs/install-and-deploy/docker.md
index ad05f4129..2e0134099 100644
--- a/docs/docs/install-and-deploy/docker.md
+++ b/docs/docs/install-and-deploy/docker.md
@@ -28,6 +28,9 @@ import TabItem from '@theme/TabItem';
 ### Using Docker Compose
 
 1. Clone the repository
+```bash
+git clone https://github.com/cardano-foundation/cardano-rosetta-java.git
+```
 2. Use the provided environment files or modify them if necessary:
    - The default configuration is in `.env.docker-compose`
    - Choose a hardware profile from the available options (see [Hardware Profiles](./hardware-profiles) for details):