docs: misc docs updates for v1.3.2 release (#586)

matiwinnetou · web-flow · commit 85ab335870be · 2025-09-05T13:21:30.000+02:00
Documentation update addressing critical issues and adding new feature
documentation for cardano-rosetta-java v1.3.2.

### Changes Made

**Removed deprecated features:**
- Deleted Catalyst voting documentation (feature removed in v1.3.0)
- Cleaned up all references in user guides and core concepts

**Fixed native assets documentation:**
- Corrected sign convention: negative values for inputs, positive for
outputs
- Replaced HEX symbols with ASCII representations in examples
- Added comprehensive minting/burning observations note
- Updated API spec with Cardano-specific terminology

**Added CIP-129 support documentation:**
- Updated DRep delegation guide for 29-byte hash support
- Clarified that `type` field remains required for all formats
- Enhanced API spec with DRep parameter descriptions

**Added performance metrics:**
- Created v1.3.2 performance test results and integrated with existing
documentation

**Fixed Docker volume path:**
- Corrected PostgreSQL volume from `/node/postgres` to
`/var/lib/postgresql/data`
diff --git a/api/src/main/resources/rosetta-specifications-1.4.15/api.yaml b/api/src/main/resources/rosetta-specifications-1.4.15/api.yaml
@@ -708,7 +708,8 @@ components:
         metadata:
           $ref: '#/components/schemas/TransactionMetadata'
     Operation:
-      description: Operations contain all balance-changing information within a transaction. They are always one-sided (only affect 1 AccountIdentifier) and can succeed or fail independently from a Transaction. Operations are used both to represent on-chain data (Data API) and to construct new transactions (Construction API), creating a standard interface for reading and writing to blockchains.
+      description: |
+        Operations contain all balance-changing information within a transaction. They are always one-sided (only affect 1 AccountIdentifier) and can succeed or fail independently from a Transaction. Operations are used both to represent on-chain data (Data API) and to construct new transactions (Construction API), creating a standard interface for reading and writing to blockchains.\n        \n        For Cardano: Input operations use negative values for both ADA and native tokens (in tokenBundle metadata). Output operations use positive values. See https://cardano-foundation.github.io/cardano-rosetta-java/docs/user-guides/multi-assets for details.
       type: object
       required:
         - operation_identifier
@@ -748,26 +749,28 @@ components:
         - currency
       properties:
         value:
-          description: Value of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 BTC would be represented by a value of 100000000.
+          description: Value of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 ADA would be represented by a value of 1000000 (since ADA has 6 decimals).
           type: string
           example: '1238089899992'
         currency:
           $ref: '#/components/schemas/Currency'
         metadata:
           type: object
     Currency:
-      description: Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).
+      description: Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Lovelaces for ADA, or smallest unit for native tokens) to standard units (ADA or token units).
       type: object
       required:
         - symbol
         - decimals
       properties:
         symbol:
-          description: Canonical symbol associated with a currency.
+          description: |
+            Canonical symbol associated with a currency. For Cardano native tokens, this should be the ASCII representation of the token name. 
+            Empty string "" should be used when a token has no name.
           type: string
-          example: BTC
+          example: ADA
         decimals:
-          description: Number of decimal places in the standard unit representation of the amount. For example, BTC has 8 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10.
+          description: Number of decimal places in the standard unit representation of the amount. For example, ADA has 6 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10.
           type: integer
           format: int32
           minimum: 0
@@ -1743,7 +1746,9 @@ components:
         size: 12378
         lockTime: 1582272577
     OperationMetadata:
-      description: OperationMetadata is used to provide any additional data needed for an Operation. It is important to populate this object with any data a consumer will need to fully understand an Operation.
+      description: |
+        OperationMetadata provides additional data needed for an Operation. For Cardano-specific operations, this includes native token bundles, staking credentials, and governance parameters. 
+        See https://cardano-foundation.github.io/cardano-rosetta-java/docs/core-concepts/cardano-addons for Cardano-specific metadata documentation.
       type: object
       properties:
         withdrawalAmount:
@@ -1761,7 +1766,7 @@ components:
           description: Pool key as hex bytes.
           type: string
         drep:
-          description: DRep
+          description: DRep parameters for vote delegation operations
           $ref: '#/components/schemas/DRepParams'
         poolGovernanceVoteParams:
           description: PoolGovernanceVoteParams contains parameters related to casting a governance vote by a pool operator.
@@ -1771,7 +1776,9 @@ components:
           description: Epoch
           type: integer
         tokenBundle:
-          description: TokenBundle
+          description: |
+            Native token bundle associated with the operation. Token values MUST be negative for input operations (spending) and positive for output operations (receiving). 
+            See documentation at https://cardano-foundation.github.io/cardano-rosetta-java/docs/user-guides/multi-assets for details.
           type: array
           items:
             $ref: '#/components/schemas/TokenBundleItem'
@@ -1844,34 +1851,50 @@ components:
           description: votingSignature
           type: string
     TokenBundleItem:
-      description: TokenBundleItem
+      description: |
+        Represents a collection of native tokens under a single policy ID. Used in tokenBundle metadata to track native assets in operations.
+        Note: Minting and burning are not supported through Construction API - only transfers of existing tokens.
       type: object
       properties:
         policyId:
-          description: PolicyId
+          description: The policy ID that controls these native tokens (hex string)
           type: string
         tokens:
-          description: Tokens
+          description: |
+            Array of token amounts under this policy. Values must be negative for inputs (spending) and positive for outputs (receiving).
+            Symbol should be the ASCII representation of the token name.
           type: array
           items:
             $ref: '#/components/schemas/Amount'
     DRepTypeParams:
-      description: DRepTypeParams
+      description: Type of DRep delegation (key_hash, script_hash, no_confidence, or abstain)
       type: string
       enum:
         - key_hash
         - script_hash
         - no_confidence
         - abstain
     DRepParams:
-        description: DRep
+        description: |
+          Delegated Representative (DRep) parameters for vote delegation.
+          Supports CIP-129 format: accepts both 29-byte hashes (with prefix) and 28-byte raw hashes.
+          The type field is required for all formats.
+          See https://cardano-foundation.github.io/cardano-rosetta-java/docs/user-guides/drep-delegation for details.
         type: object
+        required:
+          - type
         properties:
             id:
-              description: DRepId
+              description: |
+                DRep identifier. For key_hash and script_hash types:
+                - Accepts 29-byte hash with CIP-129 prefix (e.g., "03" for key_hash)
+                - Accepts 28-byte raw hash without prefix
+                - The API automatically strips the prefix if present
+                Not required for abstain and no_confidence types.
               type: string
+              example: "74984fae4ca1715fa1f8759f9d871015ac87f449a85dea6cf9956da1"
             type:
-              description: DRepType
+              description: Type of DRep delegation. Required for all operations.
               $ref: '#/components/schemas/DRepTypeParams'
     PoolRegistrationParams:
       description: PoolRegistrationParams
@@ -2039,11 +2062,11 @@ components:
           description: 'ChainCode '
           type: string
     CurrencyMetadata:
-      description: ''
+      description: 'Cardano-specific metadata for native tokens'
       type: object
       properties:
         policyId:
-          description: ''
+          description: 'The policy ID that controls this native token (hex string). Required for all non-ADA currencies.'
           type: string
     ConstructionMetadataRequestOption:
       description: ''
diff --git a/docker/readme.md b/docker/readme.md
@@ -62,10 +62,10 @@ If you want to use already existing cardano data, you can mount the data volume
 
 ### 6. Volume with Postgres data
 ````
-docker run --env-file .\docker\.env.dockerfile --env-file ./docker/.env.docker-profile-mid-level -p 8082:8082 -v {custom_folder}:/node/postgres --shm-size=4g -d {image_name}:latest
+docker run --env-file .\docker\.env.dockerfile --env-file ./docker/.env.docker-profile-mid-level -p 8082:8082 -v {custom_folder}:/var/lib/postgresql/data --shm-size=4g -d {image_name}:latest
 ````
 
-You can mount a volume with Postgres node data to ``/node/postgres`` point to use already existed data.  
+You can mount a volume with Postgres node data to ``/var/lib/postgresql/data`` point to use already existed data.  
 If the mounted volume does not contain the database or empty, new database will be created there.
 
 ### 7. Volume with custom network configurations
diff --git a/docs/docs/core-concepts/cardano-addons.md b/docs/docs/core-concepts/cardano-addons.md
@@ -27,7 +27,6 @@ Cardano Rosetta supports all operations available within the Cardano blockchain:
 - <a href="/cardano-rosetta-java/api#model/OperationMetadata" target="_blank">`Withdrawal`</a> - Withdraws rewards from a reward account
 - <a href="/cardano-rosetta-java/api#model/PoolRegistrationParams" target="_blank">`Pool_Registration`</a> - Registers a stake pool
 - <a href="/cardano-rosetta-java/api#model/OperationMetadata" target="_blank">`Pool_Retirement`</a> - Retires a stake pool
-- <a href="/cardano-rosetta-java/api#model/VoteRegistrationMetadata" target="_blank">`Vote_Registration`</a> - Registers for voting (Catalyst)
 - <a href="/cardano-rosetta-java/api#model/DRepParams" target="_blank">`dRepVoteDelegation`</a> - Delegates voting power to a Delegated Representative (DRep) for Cardano governance
 
 To support these operations, extra metadata is added to the standard Rosetta operation structure:
@@ -43,7 +42,6 @@ To support these operations, extra metadata is added to the standard Rosetta ope
   "tokenBundle": { "type": "TokenBundleItem" },
   "poolRegistrationCert": { "type": "string" },
   "poolRegistrationParams": { "type": "PoolRegistrationParams" },
-  "voteRegistrationMetadata": { "type": "VoteRegistrationMetadata" },
   "drep": { "type": "DRepObject" }
 }
 ```
@@ -102,8 +100,15 @@ For transaction fields for the `size` and `scriptSize` are added to Transaction
 
 ### `/block/transactions`
 
-When the block requested contains transactions with multi assets operations, the token bundles associated to each operation will be returned as metadata as follows:
+When the block requested contains transactions with multi assets operations, the token bundles associated to each operation will be returned as metadata. 
 
+:::note
+Token values are negative for input operations (spending) and positive for output operations (receiving).
+
+For comprehensive documentation on native token operations, including sign conventions, minting/burning observations, and construction examples, see the [Native Tokens User Guide](/user-guides/multi-assets).
+:::
+
+**Example for an input operation (spending tokens):**
 ```json
 {
   "metadata": {
@@ -114,7 +119,7 @@ When the block requested contains transactions with multi assets operations, the
           {
             "value": "-5",
             "currency": {
-              "symbol": "6a78546f6b656e31",
+              "symbol": "jxToken1",
               "decimals": 0
             }
           }
@@ -156,7 +161,7 @@ For accounts that have a multi asset balance, these will be returned with the co
     {
       "value": "10",
       "currency": {
-        "symbol": "7376c3a57274",
+        "symbol": "jxToken1",
         "decimals": 0,
         "metadata": {
           "policyId": "fc5a8a0aac159f035a147e5e2e3eb04fa3b5e67257c1b971647a717d"
@@ -377,6 +382,4 @@ In order to support Byron addresses an extra field called `chain_code` in the `a
 
 Both `signed_unsigned` and `unsigned_transaction` don't correspond to a valid Cardano Transaction that can be forwarded to the network as they contain extra data required in the Rosetta workflow. This means that such transactions cannot be decoded nor sent directly to a `cardano-node`.
 
-Transaction's metadata, needed for example for vote registration operations, is also encoded as extra data.
-
 There is no expectation that the transactions which are constructed in Rosetta can be parsed by network-specific tools or broadcast on a non-Rosetta node. All parsing and broadcast of these transactions will occur exclusively over the Rosetta API.
diff --git a/docs/docs/development/performance-measurements.md b/docs/docs/development/performance-measurements.md
@@ -7,6 +7,8 @@ description: Performance measurement methodologies and results
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
+import MidDockerCompose132 from './test-results/1.3.2/mid_profile/docker-compose.md';
+
 import AdvDockerCompose131_pruned  from './test-results/1.3.1/advanced_profile/docker-compose-pruned.md';
 import MidDockerCompose131 from './test-results/1.3.1/mid_profile/docker-compose.md';
 
@@ -57,6 +59,27 @@ Load tests are conducted using Apache Bench (ab) with a ramp-up strategy, progre
 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>
+### v1.3.2 (Sep 5, 2025)
+</summary>
+- [Release Notes](https://github.com/cardano-foundation/cardano-rosetta-java/releases/tag/1.3.2)
+
+<details>
+<summary>
+ **Mid-level Hardware Profile** 
+</summary>
+**Machine Specs:** 8 cores, 8 threads, 47GB RAM, 3.9TB NVMe, QEMU Virtual CPU v2.5+
+<details>
+<Tabs>
+  <TabItem value="mid_docker_compose132" label="Docker Compose" default>
+    <MidDockerCompose132 />
+  </TabItem>
+</Tabs>
+</details>
+</details>
+</details>
+
 <details>
 <summary>
 ### v1.3.1 (Aug 7, 2025)
diff --git a/docs/docs/development/test-results/1.3.2/mid_profile/docker-compose.md b/docs/docs/development/test-results/1.3.2/mid_profile/docker-compose.md
@@ -0,0 +1,11 @@
+The performance metrics in this table were measured against an SLA of 1000 ms.
+
+| ID | Endpoint                | Max Concurrency | p95 (ms) | p99 (ms) | Non-2xx | Error Rate (%) | Reqs/sec   |
+|----|-------------------------|------------------|----------|----------|----------|------------------|-----------|
+| 1  | /network/status         | 500              | 187      | 223      | 0        | 0.00%            | 4763.58   |
+| 2  | /account/balance        | 200              | 850      | 990      | 0        | 0.00%            | 340.34    |
+| 3  | /account/coins          | 200              | 837      | 967      | 0        | 0.00%            | 357.62    |
+| 4  | /block                  | 150              | 579      | 703      | 0        | 0.00%            | 434.22    |
+| 5  | /block/transaction      | 200              | 648      | 905      | 151      | 0.57%            | 433.11    |
+| 6  | /search/transactions    | 175              | 127      | 169      | 4        | 0.01%            | 2041.35   |
+| 7  | /construction/metadata  | 500              | 125      | 247      | 0        | 0.00%            | 9043.61   |
diff --git a/docs/docs/install-and-deploy/docker.md b/docs/docs/install-and-deploy/docker.md
@@ -227,12 +227,12 @@ docker restart yaci-indexer
 
 ### Important Container Paths
 
-| Path             | Description                |
-| ---------------- | -------------------------- |
-| `/node/db`       | Cardano Node Data          |
-| `/node/postgres` | PostgreSQL Data            |
-| `/networks`      | Network config location    |
-| `/logs`          | Log files for each service |
+| Path                       | Description                |
+| -------------------------- | -------------------------- |
+| `/node/db`                 | Cardano Node Data          |
+| `/var/lib/postgresql/data` | PostgreSQL Data            |
+| `/networks`                | Network config location    |
+| `/logs`                    | Log files for each service |
 
 ## Running Integration Tests
 
diff --git a/docs/docs/user-guides/_category_.json b/docs/docs/user-guides/_category_.json
@@ -3,6 +3,6 @@
   "position": 4,
   "link": {
     "type": "generated-index",
-    "description": "Comprehensive guides for working with Cardano Rosetta API implementation. These guides cover various Cardano-specific operations including multi-asset transactions, staking, pool operations, Catalyst voting, and DRep delegation."
+    "description": "Comprehensive guides for working with Cardano Rosetta API implementation. These guides cover various Cardano-specific operations including multi-asset transactions, staking, pool operations, and DRep delegation."
   }
 } 
diff --git a/docs/docs/user-guides/catalyst-voting.md b/docs/docs/user-guides/catalyst-voting.md
diff --git a/docs/docs/user-guides/drep-delegation.md b/docs/docs/user-guides/drep-delegation.md
diff --git a/docs/docs/user-guides/multi-assets.md b/docs/docs/user-guides/multi-assets.md

Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,6 @@`
`3`	`3`	`"position": 4,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`		`- "description": "Comprehensive guides for working with Cardano Rosetta API implementation. These guides cover various Cardano-specific operations including multi-asset transactions, staking, pool operations, Catalyst voting, and DRep delegation."`
	`6`	`+ "description": "Comprehensive guides for working with Cardano Rosetta API implementation. These guides cover various Cardano-specific operations including multi-asset transactions, staking, pool operations, and DRep delegation."`
`7`	`7`	`}`
`8`	`8`	`}`