feat: token registry integration into Rosetta API part 12.

Author: Mateusz Czeladka

CLAUDE.md

@@ -75,6 +75,8 @@ docker exec rosetta tail -f /logs/indexer.log
 - Controller implementations in `api/{domain}/controller/` implement generated interfaces
 - Always use @Nullable annotation in case of optional fields for function methods parameter inputs and outputs, records, DTOs, and entities
 - Avoid if { return } else {} , if we already have a return statement, we can just return the value, no need for else block
+- Use @NotNull annotation everywhere where we can be sure that value will not be null, use @Nullable in case value can be null sometimes
+- Considering that we will have @NotNull and @Nullable annotations, just put nulls checks only when you actually need it, if a field / property is annotated with @NonNull, there is no need for a null check in the code
 
 ### Database Architecture
 - **Hibernate JPA** for standard ORM operations

api/src/main/java/org/cardanofoundation/rosetta/api/account/model/domain/Utxo.java

@@ -1,12 +1,14 @@
 package org.cardanofoundation.rosetta.api.account.model.domain;
 
-import java.util.List;
-
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+import javax.validation.constraints.NotNull;
+import java.util.ArrayList;
+import java.util.List;
+
 @Data
 @AllArgsConstructor
 @NoArgsConstructor
@@ -16,7 +18,10 @@ public class Utxo {
   private String txHash;
   private Integer outputIndex;
   private String ownerAddr;
-  private List<Amt> amounts;
+
+  @NotNull
+  @Builder.Default
+  private List<Amt> amounts = new ArrayList<>();
 
   public Utxo(String txHash, Integer outputIndex) {
     this.txHash = txHash;

api/src/main/java/org/cardanofoundation/rosetta/api/account/service/LedgerAccountServiceImpl.java

@@ -67,6 +67,7 @@ public List<Utxo> findUtxoByAddressAndCurrency(String address, List<CurrencyRequ
   private Utxo createUtxoModel(List<CurrencyRequest> currencies, AddressUtxoEntity entity) {
     Utxo utxo = addressUtxoEntityToUtxo.toDto(entity);
     utxo.setAmounts(getAmts(currencies, entity));
+
     return utxo;
   }
 

api/src/main/java/org/cardanofoundation/rosetta/api/common/service/TokenRegistryService.java

@@ -5,11 +5,13 @@
 import org.cardanofoundation.rosetta.api.account.model.domain.Utxo;
 import org.cardanofoundation.rosetta.api.block.model.domain.BlockTx;
 import org.cardanofoundation.rosetta.api.common.model.Asset;
-import org.openapitools.client.model.Amount;
 import org.openapitools.client.model.BlockTransaction;
 import org.openapitools.client.model.CurrencyMetadataResponse;
 import org.openapitools.client.model.Operation;
 
+import lombok.NonNull;
+import javax.annotation.Nullable;
+import javax.validation.constraints.NotNull;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -26,50 +28,50 @@ public interface TokenRegistryService {
      * @param assets Set of Asset objects containing policyId and optional assetName
      * @return Map of Asset -> CurrencyMetadataResponse with metadata (always returns at least policyId)
      */
-    Map<Asset, CurrencyMetadataResponse> getTokenMetadataBatch(Set<Asset> assets);
+    Map<Asset, CurrencyMetadataResponse> getTokenMetadataBatch(@NotNull Set<Asset> assets);
 
     /**
      * Extract all native token assets from a BlockTx (inputs and outputs)
      * @param blockTx The block transaction to extract assets from
      * @return Set of unique Asset objects found in the transaction
      */
-    Set<Asset> extractAssetsFromBlockTx(BlockTx blockTx);
+    Set<Asset> extractAssetsFromBlockTx(@NonNull BlockTx blockTx);
 
     /**
      * Extract all native token assets from a list of BlockTransaction objects
      * @param transactions List of BlockTransaction objects from search results
      * @return Set of unique Asset objects found across all transactions
      */
-    Set<Asset> extractAssetsFromBlockTransactions(List<BlockTransaction> transactions);
+    Set<Asset> extractAssetsFromBlockTransactions(@NotNull List<BlockTransaction> transactions);
 
     /**
      * Extract assets from a list of Amt objects (utility method)
      * @param amounts List of amounts potentially containing native tokens
      * @return Set of unique Asset objects (excludes ADA/lovelace)
      */
-    Set<Asset> extractAssetsFromAmounts(List<Amt> amounts);
+    Set<Asset> extractAssetsFromAmounts(@NonNull List<Amt> amounts);
 
     /**
      * Extract assets from a list of Operation objects
      * @param operations List of operations potentially containing native tokens
      * @return Set of unique Asset objects found in operation amounts
      */
-    Set<Asset> extractAssetsFromOperations(List<Operation> operations);
+    Set<Asset> extractAssetsFromOperations(@NotNull List<Operation> operations);
 
     /**
      * Convenience method to extract assets and fetch metadata for a BlockTx in one call
      * @param blockTx The block transaction to process
      * @return Map of Asset -> CurrencyMetadataResponse with metadata
      */
-    Map<Asset, CurrencyMetadataResponse> fetchMetadataForBlockTx(BlockTx blockTx);
+    Map<Asset, CurrencyMetadataResponse> fetchMetadataForBlockTx(@NotNull BlockTx blockTx);
 
     /**
      * Convenience method to extract assets and fetch metadata for BlockTransactions in one call
      * @param transactions List of BlockTransaction objects from search results
      * @return Map of Asset -> CurrencyMetadataResponse with metadata
      */
-    Map<Asset, CurrencyMetadataResponse> fetchMetadataForBlockTransactions(List<BlockTransaction> transactions);
-    
+    Map<Asset, CurrencyMetadataResponse> fetchMetadataForBlockTransactions(@NotNull List<BlockTransaction> transactions);
+
     /**
      * Convenience method to extract assets and fetch metadata for a list of BlockTx objects in one call.
      * This method handles the common pattern of processing multiple transactions and fetching their metadata
@@ -78,20 +80,20 @@ public interface TokenRegistryService {
      * @param blockTxList List of BlockTx objects to process
      * @return Map of Asset -> CurrencyMetadataResponse with metadata (empty map if no native tokens)
      */
-    Map<Asset, CurrencyMetadataResponse> fetchMetadataForBlockTxList(List<BlockTx> blockTxList);
+    Map<Asset, CurrencyMetadataResponse> fetchMetadataForBlockTxList(@NotNull List<BlockTx> blockTxList);
 
     /**
      * Extract all native token assets from AddressBalance list and fetch metadata in a single batch call
      * @param balances List of address balances potentially containing native tokens
      * @return Map of Asset -> CurrencyMetadataResponse with metadata
      */
-    Map<Asset, CurrencyMetadataResponse> fetchMetadataForAddressBalances(List<AddressBalance> balances);
+    Map<Asset, CurrencyMetadataResponse> fetchMetadataForAddressBalances(@NotNull List<AddressBalance> balances);
 
     /**
      * Extract all native token assets from UTXO list and fetch metadata in a single batch call
      * @param utxos List of UTXOs potentially containing native tokens
      * @return Map of Asset -> CurrencyMetadataResponse with metadata
      */
-    Map<Asset, CurrencyMetadataResponse> fetchMetadataForUtxos(List<Utxo> utxos);
+    Map<Asset, CurrencyMetadataResponse> fetchMetadataForUtxos(@NotNull List<Utxo> utxos);
 
 }