CORE-16615: introduce new api to find an unconsumed states

data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/FindUnconsumedVisibleExactStates.avsc

@@ -0,0 +1,13 @@
+{
+  "type": "record",
+  "name": "FindUnconsumedStatesByExactType",
+  "doc": "Retrieve the unconsumed visible states of specific type. This only retrieves exact type excluding its states of subclass unlike {@link FindUnconsumedStatesByType}. One of several types of ledger persistence request {@link LedgerPersistenceRequest}",
+  "namespace": "net.corda.data.ledger.persistence",
+  "fields": [
+    {
+      "name": "stateClassName",
+      "type": "string",
+      "doc": "The fully qualified state class name"
+    }
+  ]
+}

data/avro-schema/src/main/resources/avro/net/corda/data/ledger/persistence/LedgerPersistenceRequest.avsc

@@ -34,6 +34,7 @@
         "net.corda.data.ledger.persistence.PersistTransactionIfDoesNotExist",
         "net.corda.data.ledger.persistence.FindTransaction",
         "net.corda.data.ledger.persistence.FindUnconsumedStatesByType",
+        "net.corda.data.ledger.persistence.FindUnconsumedStatesByExactType",
         "net.corda.data.ledger.persistence.ResolveStateRefs",
         "net.corda.data.ledger.persistence.UpdateTransactionStatus",
         "net.corda.data.persistence.FindWithNamedQuery",

gradle.properties

@@ -9,7 +9,7 @@ cordaProductVersion = 5.1.0
 # NOTE: update this each time this module contains a breaking change
 ## NOTE: currently this is a top level revision, so all API versions will line up, but this could be moved to
 ##   a per module property in which case module versions can change independently.
-cordaApiRevision = 22
+cordaApiRevision = 23
 
 # Main
 kotlinVersion = 1.8.21

ledger/ledger-utxo/src/main/java/net/corda/v5/ledger/utxo/UtxoLedgerService.java

@@ -87,7 +87,14 @@ public interface UtxoLedgerService {
     UtxoFilteredTransactionBuilder filterSignedTransaction(@NotNull UtxoSignedTransaction transaction);
 
     /**
-     * Finds unconsumed states of the specified {@link ContractState} type in the vault.
+     * Finds unconsumed states that are concrete implementations or subclasses of {@code type}.
+     * <p>
+     * Only use this method if subclasses of {@code type} must be returned.
+     * <p>
+     * Use {@link #findUnconsumedStatesByExactType(Class<T>)} to return exact instances of the input {@code type}.
+     * This method is more performant than {@link #findUnconsumedStatesByType(Class<T>)}.
+     * <p>
+     * Use {@link #query(String, Class)} for a more performant method of retrieving subclasses of a specified type.
      *
      * @param <T>  The underlying {@link ContractState} type.
      * @param type The {@link ContractState} type to find in the vault.
@@ -97,6 +104,17 @@ public interface UtxoLedgerService {
     @Suspendable
     <T extends ContractState> List<StateAndRef<T>> findUnconsumedStatesByType(@NotNull Class<T> type);
 
+    /**
+     * Finds unconsumed states of the specified {@link ContractState} type in the vault.
+     *
+     * @param <T>  The underlying {@link ContractState} type.
+     * @param type The {@link ContractState} type to find in the vault.
+     * @return Returns a {@link List} of {@link StateAndRef} of unconsumed states of the specified type, or an empty list if no states could be found.
+     */
+    @NotNull
+    @Suspendable
+    <T extends ContractState> List<StateAndRef<T>> findUnconsumedStatesByExactType(@NotNull Class<T> type);
+
     /**
      * Verifies, signs, collects signatures, records and broadcasts a {@link UtxoSignedTransaction} to participants and observers.
      *