docs: misc docusaurus improvements + update for v1.2.9 (#478)

* chore: update OpenAPI specification and documentation visual improvements

- Updated API title to reflect rebranding to Mesh API.
- Enhanced some endpoint descriptions for clarity and accuracy (network status, options, block transaction).
- Added detailed descriptions for Cardano-specific transaction and block metadata.
- Commented out unimplemented mempool endpoints and related documentation.
- Improved Docusaurus configuration for better user experience, including last update timestamps .
- Updated CSS for improved layout and styling consistency across documentation pages.

* chore: update OpenAPI specification for java implementation

- Updated example values for block, account and transaction identifiers to align with current data.
- Enhanced operation types and statuses to include Cardano-specific options.
- Added valid response examples to improve clarity.
- Commented out unimplemented features and provided TODO notes for future implementation.

* chore: update Docusaurus configuration and CSS for improved documentation layout

- Updated custom CSS to enhance layout consistency, including centering the navbar and main wrapper.
- Removed the proxy URL from the configuration.
- Adjusted styles for the theme edit button and sidebar to improve user experience.
- Deleted the outdated API specification file to streamline documentation.

* chore: update dependencies in package.json and yarn.lock

* chore: restore SearchTransactionsResponse schema to specs

* fix: remove schema 'examples' breaking CI validation

Remove multiple 'examples' entries from schema definitions ('Operation', 'NetworkIdentifier'). These were intended solely for enhanced rendering in Scalar docs but caused spec-validation failures during CI builds.

Single 'example' per schema retained to ensure OpenAPI compliance and fix build errors.

* chore: update OpenAPI generator plugin version and refine example values in API specification

- Upgraded the OpenAPI generator Maven plugin from version 6.4.0 to 7.13.0.
- Simplified example values in the API specification by removing unnecessary array structures for 'network' and 'status' fields.

* chore: drop API spec and pom edits from PR 456

* chore: update Docker compose command and version in documentation

* refactor: update documentation for spent UTXO pruning

- Renamed "Pruning UTXOs" to "Spent UTXO Pruning" for clarity.
- Enhanced explanations regarding the impact and configuration of spent UTXO pruning.
- Updated resource requirements in README and intro documentation to specify spent UTXO pruning.

* docs: enhance documentation for queryng stake addresses and rename multi-assets section

- Added a note on stake addresses to clarify the response from the `/account/balance` endpoint when queried with a stake address (available rewards).
- Renamed the "Multi-Assets" section to "Native Tokens" for better alignment with terminology used in Cardano documentation.

* docs: update performance measurement documentation and environment variables

- Enhanced the performance measurements section with load test results for versions 1.2.6, 1.2.7, and 1.2.9.
- Updated environment variables documentation to reflect changes in version 1.2.9, including the introduction of `REMOVE_SPENT_UTXOS` and `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT`, while deprecating older variables.

* docs: update storage requirements and pruning notes in documentation

- Revised storage requirements in README and intro documentation to reflect updated values for both pruning enabled and disabled scenarios.
- Added clarifications regarding the limitations of searching transactions by address when pruning is enabled in the pruning and cardano-addons documentation.

Author: linconvidal

README.md

@@ -29,8 +29,8 @@ Since [Yaci-Store](https://github.com/bloxbean/yaci-store) is a comparatively li
 
 - 4CPU Cores
 - 32GB RAM
-- ca. > 1TB of storage (REMOVE_SPENT_UTXOS=false) [default]
-- ca > 400GB of storage (REMOVE_SPENT_UTXOS=true)
+- ~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
 
 Better hardware will improve the performance of the indexer and the node, which will result in faster syncing times.
 
@@ -124,7 +124,7 @@ This will start:
 ### Entry level hardware profile
 
 ```bash
-   docker-compose --env-file .env.docker-compose --env-file .env.docker-compose-profile-mid-level -f docker-compose.yaml up -d
+   docker compose --env-file .env.docker-compose --env-file .env.docker-compose-profile-mid-level -f docker-compose.yaml up -d
 ```
 
 ### A complete list of hardware profiles:

docs/docs/advanced-configuration/pruning.md

@@ -1,44 +1,134 @@
 ---
 sidebar_position: 1
-title: Remove Spent UTXOs
-description: Optimizing disk usage with removal of spent UTxOs
+title: Spent UTXO Pruning
+description: Optimizing disk usage with spent UTXO pruning
 ---
 
-# Remove Spent UTXOs
+# Spent UTXO Pruning
 
-This guide explains how to optimize disk usage in **cardano-rosetta-java** through removal of spent utxo (a special rosetta-java specific form of pruning).
+This guide explains how to optimize disk usage in **cardano-rosetta-java** through spent UTXO pruning, including its impact on Rosetta API endpoints and configuration options.
 
-## What is UTxO Spent Pruning (removal of spent UTxOs)?
+## Understanding Spent UTXO Pruning
 
-UTxO Spent Pruning removes spent (consumed) UTXOs from local storage, keeping only unspent UTXOs. This can reduce on-disk storage from ~1TB down to ~400GB, but discards historical transaction data.
+Spent UTXO pruning is a disk optimization mechanism in `cardano-rosetta-java`, powered by its underlying indexer, Yaci-Store. This feature selectively removes data related to spent UTXOs from the local database.
 
-- Only unspent outputs are preserved.
-- You can still validate the chain's current state (and spend tokens), since active UTXOs remain.
-- You should be able to build transaction because only spent UTxOs are removed (unspent stay)
+**Core Principles:**
+
+- **Targeted Deletion**: Only _spent_ UTXOs are removed. All _current, unspent_ UTXOs are preserved, ensuring the accuracy of the present blockchain state and balances.
+- **Distinction from Other Pruning**: This mechanism differs from what is commonly understood as 'pruning' in some other blockchain contexts, including certain descriptions in the Coinbase Mesh API (formerly Rosetta). Unlike methods such as Bitcoin's pruning (which removes entire historical blocks), our approach retains full block history but selectively trims the UTXO set by removing only spent outputs.
+
+**How it Works:**
+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.
+
+**Impact Summary:**
+| Aspect | Effect |
+| :------------------------- | :----------------------------------------------------------- |
+| **Disk Storage** | ✅ Significantly reduced (e.g., mainnet from ~1TB to ~500GB) |
+| **Current UTXO Set** | ✅ Fully preserved; current balances remain accurate |
+| **Historical Spent UTXOs** | ⚠️ Permanently deleted beyond the safety margin |
+| **Query Performance** | ✅ Improved for queries against the current UTXO set |
+
+## 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).
+
+:::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.
+:::
+
+| **Endpoint**           | **Current State** | **Historical Queries** | **Impact & Notes**                                                           |
+| ---------------------- | ----------------- | ---------------------- | ---------------------------------------------------------------------------- |
+| `/account/balance`     | ✅ Works          | ⚠️ Limited             | **Low** - Current balances unaffected                                        |
+| `/account/coins`       | ✅ Works          | ⚠️ Limited             | **Low** - Current UTXO lists complete                                        |
+| `/block`               | ✅ Recent only    | ❌ Incomplete          | **High** - Missing old transaction inputs                                    |
+| `/block/transaction`   | ✅ Recent only    | ❌ Incomplete          | **High** - Missing spent UTXOs operation details                             |
+| `/search/transactions` | ⚠️ Recent only    | ❌ Limited             | **Medium** - Hash search works, address limited                              |
+| `/network/status`      | ✅ Works          | ✅ Works               | **None** - Returns additional `oldest_block_identifier` when pruning enabled |
+| `/network/*`           | ✅ Works          | ✅ Works               | **None** - Independent of UTXO data                                          |
+| `/construction/*`      | ✅ Works          | ✅ Works               | **None** - Uses current UTXOs only                                           |
+
+After enabling pruning, searching for transactions by their hash will always work, because transaction records themselves are never pruned. However, searching by address is limited: address-based searches rely on the UTXO set, and once spent UTXOs older than the pruning window are deleted, only transactions involving current or recently spent UTXOs can be found by address. Older history is not returned once pruned.
 
 **Enable Spent UTxO removal **: Set `REMOVE_SPENT_UTXOS=true` in your environment (e.g., in `.env.dockerfile` or `.env.docker-compose`).
 **Disable Spent UTxO removal ** (default): Set `REMOVE_SPENT_UTXOS=false`.
 
 ## When Spent UTxO Removal should be enabled?   
 
-- **Low Disk Environments**: If you need to minimize disk usage and only require UTXO data for current balances.
-- **Exploratory / Dev Environments**: If historical queries are not critical.
-- **Performance**: if you are running into performance / scalability issues, i.e. especially on /account/balance when working with large addresses
+:::tip Recommended Use Cases
+Pruning is beneficial in scenarios where optimizing disk space and focusing on current data is prioritized over maintaining a complete historical record. Consider enabling pruning if your use case aligns with the following:
+
+- **Exchange Integrations & Wallet Services**: Primarily for tracking current balances, processing recent deposits/withdrawals, and validating recent transactions.
+- **Resource-Constrained Environments**: Ideal when disk space is a significant limitation (e.g., under 1TB available for mainnet data).
+- **Tip-of-Chain Operations**: For applications focused on the latest blockchain state rather than deep historical analysis.
+- **Development and Testing**: Useful when a full historical dataset is not essential for development or testing purposes.
+  :::
 
 ## When to avoid setting UtxO Removal feature?
 
-- **Full Historical Data Requirements**: If you need the complete transaction history—whether for exchange operations, audit trails, or compliance mandates—do not enable pruning. Pruning discards spent UTXOs, which removes older transaction data and prevents certain types of historical lookups or reporting.
+:::warning Not Suitable For
+Avoid pruning if your operational or regulatory requirements necessitate access to complete and auditable historical blockchain data. Pruning is generally not suitable if you need:
+
+- **Complete Historical Data & Deep Queries**: For comprehensive auditing, compliance, data analytics, or block explorer-like functionality that requires querying full transaction history from any point in time.
+- **Strict Compliance and Audit Trails**: If regulatory mandates demand immutable, complete historical records. Pruned data cannot be recovered without a full resync, and historical queries for `/block` and `/block/transaction` become unreliable beyond the safety window.
+  :::
+
+:::danger Data Loss Warning
+Once data is pruned, it cannot be recovered without a full blockchain resynchronization. Assess your historical data needs carefully before enabling pruning.
+:::
 
-## Example Configuration
+## Configuration
 
-Below is a snippet of how you might configure `.env.dockerfile` or `.env.docker-compose` for pruning:
+Spent UTXO pruning is configured via environment variables, typically set in your `.env.dockerfile` or `.env.docker-compose` file. Below is an example demonstrating the available settings and their default values:
 
 ```bash
-# --- Remove Spent UTxOs Toggle ---
+# --- Spent UTXO Pruning Configuration ---
+
+# Enable or disable spent UTXO pruning.
+# Default: false (Pruning is disabled by default)
+# To enable, set to: true
 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)
+# This value balances safety for rollbacks against storage savings.
+# Example: To keep ~24 hours of spent UTXOs, set to 4320.
+# 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
 ```
 
+:::note Configuration Guidelines
+
+- Start with the default settings (`REMOVE_SPENT_UTXOS=false` means pruning is initially off).
+- If enabling, the provided defaults (`REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT=2160`) are sensible starting points.
+- Adjust `REMOVE_SPENT_UTXOS_LAST_BLOCKS_GRACE_COUNT` based on your specific needs for recent historical data access. A larger value offers a longer window for historical queries but increases storage.
+  :::
+
+## Migration and Operational Notes
+
+This section outlines key considerations when changing pruning settings or managing a system with pruning enabled.
+
+### Enabling Pruning on an Existing Deployment
+
+1.  **Configuration**: Update the necessary environment variables (e.g., `REMOVE_SPENT_UTXOS=true`) and restart your cardano-rosetta-java services.
+2.  **Initial Monitoring**: After enabling, closely monitor your application for any errors. Disk usage benefits will typically appear after the first pruning cycle completes.
+
+### Disabling Pruning
+
+:::caution Important Considerations
+
+- **Halts Deletion, No Restoration**: Setting `REMOVE_SPENT_UTXOS=false` and restarting services will stop further deletion of spent UTXOs. However, this action **does not restore** any data already pruned.
+- **Full Resync for Complete History**: To regain a complete historical dataset after pruning has been active, a full resynchronization of the blockchain data is required.
+- **Storage Growth Resumes**: Once pruning is disabled, expect storage usage to gradually increase again as new UTXOs (both spent and unspent) accumulate.
+  :::
+
 ## Further Reading
 
-- [Rosetta API Reference](https://docs.cdp.coinbase.com/mesh/docs/api-reference/)
+- [Environment Variables Reference](../install-and-deploy/env-vars.md)
 - [Yaci-Store Repository](https://github.com/bloxbean/yaci-store)
+- [Coinbase Mesh (formerly Rosetta) API Specification](https://docs.cdp.coinbase.com/mesh/docs/api-reference/)
+- [Cardano UTXO Model Documentation](https://docs.cardano.org/learn/eutxo-explainer/)

docs/docs/core-concepts/cardano-addons.md

@@ -73,6 +73,10 @@ Max amount of transactions allowed to be requested is defined by `PAGE_SIZE` env
 `status` and `maxBlock` filters work as excluding filters, if they are set, besides operator value.
 :::
 
+:::warning Pruning limitation
+Searching for transactions by hash is always possible, because transaction records themselves are never pruned. However, searching by address is limited: address-based searches depend on the UTXO set, and once spent UTXOs older than the pruning window are deleted, only transactions involving current or recently spent UTXOs can be found by address. Older history is not returned once pruned.
+:::
+
 ### `/block`
 
 The following metadata is also returned, when querying for block information:
@@ -163,7 +167,23 @@ For accounts that have a multi asset balance, these will be returned with the co
 }
 ```
 
-Also, `coins` will be returned with the token bundle list corresponding to each coin as metadata.
+When querying `/account/balance`, the result depends on the type of address:
+
+- For a **payment address** (Base or Enterprise), the response contains the sum of all unspent UTXOs for that address (the "spendable" balance).
+- For a **stake address** (reward address), the response contains only the available rewards that can be withdrawn from that stake address.
+
+To present a wallet's total value, clients should query both the payment address (for spendable funds) and the stake address (for rewards), then combine the results.
+
+:::info Note on Stake Addresses
+A stake address never holds UTXOs and cannot have a spendable balance. The `/account/balance` response for a stake address always reflects only the withdrawable rewards.
+:::
+
+Internally, the Rosetta service gathers these two figures from different subsystems:
+
+- **Spendable funds** (ADA and native tokens) are obtained by summing all unspent UTXOs that belong to the payment address(es). These UTXOs are stored in the PostgreSQL database maintained by the **Yaci Indexer**.
+- **Rewards balance** is fetched directly from the **Yaci Store** through a lightweight internal HTTP call, which queries the current withdrawable rewards for the stake address.
+
+As a consequence, the spendable portion updates whenever new blocks modify the UTXO set for the payment address, whereas the rewards portion changes only after the protocol distributes staking rewards (typically once per epoch).
 
 ### `/account/coins`
 

docs/docs/development/performance-measurements.md

@@ -4,36 +4,98 @@ title: Performance Measurements
 description: Performance measurement methodologies and results
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Performance Measurements
 
-This page documents the performance measurements and load test results for different releases of `cardano-rosetta-java`.
+This page documents load test results for different releases of `cardano-rosetta-java`, evaluating performance across various deployment scenarios.
+
+### Service Level Agreements (SLAs)
+
+Our performance evaluation is based on the following Service Level Agreements (SLAs), which define the acceptable thresholds for production environments:
+
+- **Response Time**: A **p99 of less than 1 second** is the target for all standard API endpoints.
+- **Error Rate**: A **non-2xx response rate of less than 1%** is considered acceptable.
 
-## Load Test Results
+In specific high-load scenarios, such as querying addresses with hundreds of thousands of transactions, these SLAs may be adjusted to assess system stability under extreme conditions. Any such adjustments are noted in the relevant test results.
 
-Below you can find the load test results for various releases, comparing different deployment options.
+:::note
+Load tests are conducted using Apache Bench (ab) with a ramp-up strategy, progressively increasing concurrency to a predefined ceiling of 500 simultaneous requests.
+:::
+
+:::tip
+To better understand the environments in which these results were obtained, please refer to our [hardware profiles documentation](../install-and-deploy/hardware-profiles).
+:::
 
 <details>
 <summary>
 
-### Release 1.2.7 (Test Run: 2025-04-16)
+### v1.2.9 (Jun 11, 2025)
 
 </summary>
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import SingleDocker from './\_test-results/1.2.6-dev_2025-04-16/single-docker.md';
-import DockerCompose from './\_test-results/1.2.6-dev_2025-04-16/docker-compose.md';
+- [Release Notes](https://github.com/cardano-foundation/cardano-rosetta-java/releases/tag/1.2.9)
+
+The following tests were conducted on a **mid-level** hardware profile with the following specifications: **8 cores, 8 threads, 47GB RAM, 3.9TB NVMe, QEMU Virtual CPU v2.5+**.
+
+import DockerCompose129 from './test-results/1.2.9/docker-compose.md';
+import HugeAddress373k from './test-results/1.2.9/huge-address-373k.md';
+import HugeAddress16M from './test-results/1.2.9/huge-address-1.6M.md';
 
 <Tabs>
-  <TabItem value="single" label="Single Docker" default>
-    <SingleDocker />
+  <TabItem value="compose" label="Docker Compose" default>
+    <DockerCompose129 />
+  </TabItem>
+  <TabItem value="huge-373k" label="Huge Address (~373k txs)">
+    <HugeAddress373k />
+  </TabItem>
+  <TabItem value="huge-1.6M" label="Huge Address (~1.6M txs)">
+    <HugeAddress16M />
   </TabItem>
+</Tabs>
+</details>
+
+<details>
+<summary>
+
+### v1.2.7 (Apr 29, 2025)
+
+</summary>
+
+import SingleDocker127 from './test-results/1.2.7/single-docker.md';
+import DockerCompose127 from './test-results/1.2.7/docker-compose.md';
+
+- [Release Notes](https://github.com/cardano-foundation/cardano-rosetta-java/releases/tag/1.2.7)
+
+<Tabs>
+  <!-- <TabItem value="single" label="Single Docker" default>
+    <SingleDocker127 />
+  </TabItem> -->
   <TabItem value="compose" label="Docker Compose">
-    <DockerCompose />
+    <DockerCompose127 />
   </TabItem>
 </Tabs>
 </details>
 
----
+<details>
+<summary>
+
+### v1.2.6 (Apr 15, 2025)
+
+</summary>
+
+import SingleDocker126 from './test-results/1.2.6/single-docker.md';
+import DockerCompose126 from './test-results/1.2.6/docker-compose.md';
+
+- [Release Notes](https://github.com/cardano-foundation/cardano-rosetta-java/releases/tag/1.2.6)
 
-_Future results will be added here, each as a collapsible section._
+<Tabs>
+  <TabItem value="single" label="Single Docker" default>
+    <SingleDocker126 />
+  </TabItem>
+  <TabItem value="compose" label="Docker Compose">
+    <DockerCompose126 />
+  </TabItem>
+</Tabs>
+</details>

docs/docs/development/qa-regression.md

@@ -8,7 +8,7 @@ description: Testing methodology and procedures for releases
 
 The following steps are performed as part of the QA process for new releases:
 
-1. **E2E Testing**: Run the complete end-to-end test flow on preprod network using the [`e2e-tests`](https://github.com/cardano-foundation/cardano-rosetta-java/tree/main/e2e-tests) suite
+1. **E2E Testing**: Run the complete end-to-end test flow on preprod network using the [`e2e_tests`](https://github.com/cardano-foundation/cardano-rosetta-java/tree/main/e2e_tests) suite
 
    - Test on both single docker and docker-compose deployments
    - Verify all construction API flows work correctly