github cardano-foundation/cardano-rosetta-java 2.3.0
on GitHub

6 hours ago

Cardano Rosetta Java v2.3.0

Cardano Rosetta Java v2.3.0 is a maintenance release that hardens transaction construction with protocol-level output validation, fixes several data-endpoint edge cases, and embeds database index management directly into the indexer.

⚠️ This is not a mandatory release.

Breaking Changes ⚠️ ⚠️ ⚠️

  • Token registry logo encoding fixed (hex → base64). Logo values in currency metadata were declared as base64 but contained the raw hex served by CIP-26 registries. They are now delivered as actual base64. Clients that worked around the old behavior by hex-decoding the value must switch to base64 decoding.
  • /search/transactions no longer accepts lovelace as a currency symbol. Previously such requests were accepted even though lovelace is not a native asset; they now return a validation error.
  • /construction/payloads enforces protocol output limits. Requests whose outputs are below the minimum UTxO requirement or exceed max_val_size now fail with a clear error instead of returning an unsigned transaction. Only transactions that the node would have rejected at submission are affected.

See API / Configuration below for error codes and full details.

Key Improvements

  • Yaci Store upgraded to 2.0.2.1 (2.0.2.1 has a permanent restart feature, see: bloxbean/yaci-store#1003)
  • Transaction construction now validates outputs against Cardano protocol limits (minimum ADA per output and maximum value size), rejecting invalid transactions early with clear errors instead of failing at submission time
  • Database index management is now embedded in the indexer — the separate index-applier container is gone, with automatic crash recovery, bounded retries of failed builds, and a dedicated monitoring endpoint. See the updated Index Management documentation.
  • Token registry (CIP-26) logos are now returned correctly encoded so images render directly in clients
  • Data endpoints stay schema-valid on pruned deployments, and multi-asset token bundles with duplicate policy IDs now parse correctly
  • Runtime migrated to JDK 25 LTS with dependency updates;

Upgrade / Compatibility

  • From v2.0.0 / v2.1.x / v2.2.0: Compatible, no resync required. On first start after the upgrade, yaci-indexer detects the already-existing database indexes and reports LIVE immediately.
  • From v1.x.x: Requires a full resync of the yaci-indexer only (Cardano Node data can be kept). See the resync procedure.
  • The index-applier one-shot container has been removed: docker-compose-index-applier.yaml no longer exists and the Helm chart no longer ships the indexApplier Job and ConfigMap. No action is needed for standard deployments; if your own orchestration or scripts referenced the index-applier container, remove those references.

API / Configuration

  • /construction/payloads: outputs are validated against the minimum UTxO requirement.

    • Each transaction output's ADA value is checked against the protocol minimum (derived from the coinsPerUtxoSize protocol parameter). Outputs below the minimum are rejected with new non-retriable error 5060 ("Output ADA value is below the minimum UTxO requirement").

  • /construction/payloads: outputs are validated against max_val_size.

    • The serialized byte size of each output's value is checked against the max_val_size protocol parameter. Oversized outputs are rejected with new non-retriable error 5061 ("UTxO value byte size exceeds the allowed max_val_size protocol parameter"). The check is skipped when max_val_size is absent or zero in the provided protocol parameters.

  • /construction/parse: token bundles with duplicate policy IDs parse correctly.

    • MultiAsset entries are now grouped by policy ID before building the token bundle, so transaction bodies containing multiple entries for the same policy no longer produce malformed operation metadata.

  • /search/transactions: lovelace rejected as currency symbol.

    • Passing lovelace (any casing) as currency.symbol now returns error 4024 ("Invalid token name"). Previously the symbol was accepted and treated as a native asset filter.

  • /block, /block/transaction, /search/transactions: empty account objects removed from operations.

    • Operations whose account address cannot be resolved (for example inputs referencing UTXOs already removed on pruned instances) no longer include an empty account object, keeping responses valid against the Rosetta schema.

  • Breaking: token registry logos converted from hex to base64.

    • CIP-26 registries serve logo bytes hex-encoded; responses now convert them to base64 as clients expect. Malformed logo values are omitted instead of being passed through. Affects currency metadata on /account/balance, /account/coins, /block, /block/transaction, and /search/transactions when the token registry integration is enabled.

  • /network/options: error list and versions updated.

    • The allow.errors list now includes codes 5060 and 5061, and version.middleware_version is 2.3.0.

  • yaci-indexer: new actuator endpoint /actuator/rosetta-indexes.

    • Reports overall and per-index lifecycle state (READY/BUILDING/FAILED/MISSING) including per-index error messages, replacing log-watching of the removed index-applier container. See Index Management for details.

Environment updates:

  • RELEASE_VERSION: 2.2.0 → 2.3.0
  • INDEX_STALL_TIMEOUT_MINUTES: 360 (new — liveness stall timeout while an index build is in progress)
  • INDEX_FAILED_RETRY_MAX_ATTEMPTS: 3 (new — retry cap after a failed index build)
  • INDEX_FAILED_RETRY_DELAY_MINUTES: 5 (new — delay between failed-build retries)
  • INDEX_QUERY_TIMEOUT_SECONDS: 21600 (new — statement timeout per index creation)

What's Changed

  • chore: migrate to JDK 25 LTS and update dependencies by @matiwinnetou in #721
  • fix: group MultiAsset entries by policyId before merging in parseToke… in #729
  • docs: fix duplicated trailing column in env-vars table by @matiwinnetou in #754
  • fix: update TOKEN_REGISTRY_BASE_URL by @Sotatek-HenryDo in #756
  • fix(search-service): reject lovelace as currency symbol in /search/tr… in #752
  • build(docker): harden apt against transient Ubuntu-mirror failures by @matiwinnetou in #739
  • UTXO size (max_val_size) validation for payload endpoints in #738
  • fix: payloads endpoint be validate min ada value during txn construction in #735
  • fix(token-registry): convert CIP-26 logo from hex to base64 before re… in #751
  • feat: replace 'apply indexes' with a native solution in #746
  • fix: block data endpoints when indexer is syncing by @Sotatek-HenryDo in #758
  • fix: integration test by @Sotatek-HenryDo in #760
  • fix: drop empty account identifier from operations by @Sotatek-HenryDo in #762
  • feat: add 5s cache for sync status verification by @Sotatek-HenryDo in #761
  • chore: bump yaci-store to 2.0.2.1 by @matiwinnetou in #765
  • feat(sync) status refresh scheduler by @Sotatek-HenryDo in #767
  • Revert sync-status gating/caching/scheduler (#758, #761, #767) by @Sotatek-HenryDo in #773
  • chore: prepare 2.3.0 by @matiwinnetou in #755

New Contributors

Full Changelog: 2.2.0...2.3.0

Check out latest releases or
releases around cardano-foundation/cardano-rosetta-java 2.3.0

Don't miss a new cardano-rosetta-java release

NewReleases is sending notifications on new releases.

Get notifications