Add searchUtxos query to cardano-rpc

Author: carbolymer

.changes/20260423_cardano_rpc_search_utxos.yml

@@ -0,0 +1,6 @@
+project: cardano-rpc
+pr: 1123
+kind:
+  - feature
+description: |
+  Add searchUtxos gRPC method to the UTxO RPC query service, implementing predicate-based UTxO filtering with address, asset, and boolean combinators, plus cursor-based pagination.

cardano-rpc/cardano-rpc.cabal

@@ -58,6 +58,7 @@ library
     Cardano.Rpc.Server.Internal.Monad
     Cardano.Rpc.Server.Internal.Node
     Cardano.Rpc.Server.Internal.Tracing
+    Cardano.Rpc.Server.Internal.UtxoRpc.Predicate
     Cardano.Rpc.Server.Internal.UtxoRpc.Query
     Cardano.Rpc.Server.Internal.UtxoRpc.Submit
     Cardano.Rpc.Server.Internal.UtxoRpc.Type
@@ -121,6 +122,7 @@ test-suite cardano-rpc-test
   type: exitcode-stdio-1.0
   build-depends:
     base,
+    bytestring,
     cardano-api,
     cardano-api:gen,
     cardano-ledger-api,
@@ -130,9 +132,11 @@ test-suite cardano-rpc-test
     containers,
     hedgehog,
     hedgehog-extras,
+    proto-lens,
     rio,
     tasty,
     tasty-hedgehog,
+    text,
     time,
 
   ghc-options:
@@ -142,6 +146,8 @@ test-suite cardano-rpc-test
 
   build-tool-depends: tasty-discover:tasty-discover
   other-modules:
+    Test.Cardano.Rpc.Pagination
+    Test.Cardano.Rpc.Predicate
     Test.Cardano.Rpc.ProtocolParameters
     Test.Cardano.Rpc.TxOutput
     Test.Cardano.Rpc.Type

cardano-rpc/gen/Proto/Utxorpc/V1beta/Cardano/Cardano.hs

@@ -516,15 +516,15 @@ message UpdateDRepCert {
 
 // Pattern of an address that can be used to evaluate matching predicates.
 message AddressPattern {
-  bytes exact_address = 1; // The address should match this exact address value.
-  bytes payment_part = 2; // The payment part of the address should match this value.
-  bytes delegation_part = 3; // The delegation part of the address should match this value.
+  optional bytes exact_address = 1; // The address should match this exact address value.
+  optional bytes payment_part = 2; // The payment part of the address should match this value.
+  optional bytes delegation_part = 3; // The delegation part of the address should match this value.
 }
 
 // Pattern of a native asset that can be used to evaluate matching predicates.
 message AssetPattern {
-  bytes policy_id = 1; // The asset should belong to this policy id
-  bytes asset_name = 2; // The asset should present this name
+  optional bytes policy_id = 1; // The asset should belong to this policy id
+  optional bytes asset_name = 2; // The asset should present this name
 }
 
 // Pattern of a certificate that can be used to evaluate matching predicates.
@@ -561,8 +561,8 @@ message PoolRetirementPattern {
 
 // Pattern of a tx output that can be used to evaluate matching predicates.
 message TxOutputPattern {
-  AddressPattern address = 1; // Match any address in the output that exhibits this pattern.
-  AssetPattern asset = 2; // Match any asset in the output that exhibits this pattern.
+  optional AddressPattern address = 1; // Match any address in the output that exhibits this pattern.
+  optional AssetPattern asset = 2; // Match any asset in the output that exhibits this pattern.
 }
 
 // Pattern of a Tx that can be used to evaluate matching predicates.

cardano-rpc/gen/Proto/Utxorpc/V1beta/Cardano/Cardano_Fields.hs

@@ -81,7 +81,7 @@ message AnyUtxoPattern {
 
 // Represents a simple utxo predicate that can composed to create more complex ones
 message UtxoPredicate {
-  AnyUtxoPattern match = 1; // Predicate is true if tx exhibits pattern.
+  optional AnyUtxoPattern match = 1; // Predicate is true if tx exhibits pattern.
   repeated UtxoPredicate not = 2; // Predicate is true if tx doesn't exhibit pattern.
   repeated UtxoPredicate all_of = 3; // Predicate is true if utxo exhibits all of the patterns.
   repeated UtxoPredicate any_of = 4; // Predicate is true if utxo exhibits any of the patterns.
@@ -111,17 +111,17 @@ message ReadUtxosResponse {
 
 // Request to search for UTxO based on a pattern.
 message SearchUtxosRequest {
-  UtxoPredicate predicate = 1; // Pattern to match UTxOs by.
+  optional UtxoPredicate predicate = 1; // Pattern to match UTxOs by.
   google.protobuf.FieldMask field_mask = 2; // Field mask to selectively return fields.
-  int32 max_items = 3; // The maximum number of items to return.
-  string start_token = 4; // The next_page_token value returned from a previous request, if any.
+  optional int32 max_items = 3; // The maximum number of items to return.
+  optional string start_token = 4; // The next_page_token value returned from a previous request, if any.
 }
 
 // Response containing the UTxOs that match the requested addresses.
 message SearchUtxosResponse {
   repeated AnyUtxoData items = 1; // List of UTxOs.
   ChainPoint ledger_tip = 2; // The chain point that represent the ledger current position.
-  string next_token = 3; // Token to retrieve the next page of results, or empty if there are no more results.
+  optional string next_token = 3; // Token to retrieve the next page of results, absent if there are no more results.
 }
 
 // Request to get data (as in plural of datum)
@@ -170,6 +170,7 @@ message ReadTxResponse {
 service QueryService {
   rpc ReadParams(ReadParamsRequest) returns (ReadParamsResponse); // Get overall chain state.
   rpc ReadUtxos(ReadUtxosRequest) returns (ReadUtxosResponse); // Read specific UTxOs by reference.
+  rpc SearchUtxos(SearchUtxosRequest) returns (SearchUtxosResponse); // Search for UTxO based on a pattern.
 
   // TODO: decide if we want to expand the scope
   // rpc DumpUtxos(ReadUtxosRequest) returns (stream ReadUtxosResponse); // Dump all available utxos

cardano-rpc/gen/Proto/Utxorpc/V1beta/Query/Query.hs

@@ -27,7 +27,10 @@ import Proto.Utxorpc.V1beta.Cardano.Cardano_Fields hiding
   , vec'values
   )
 import Proto.Utxorpc.V1beta.Query.Query
-import Proto.Utxorpc.V1beta.Query.Query_Fields
+import Proto.Utxorpc.V1beta.Query.Query_Fields hiding
+  ( maybe'tx
+  , tx
+  )
 
 type instance RequestMetadata (Protobuf QueryService meth) = NoMetadata
 

cardano-rpc/gen/Proto/Utxorpc/V1beta/Query/Query_Fields.hs

@@ -11,7 +11,27 @@ import Network.GRPC.Common
 import Network.GRPC.Common.Protobuf
 
 import Proto.Utxorpc.V1beta.Submit.Submit
-import Proto.Utxorpc.V1beta.Submit.Submit_Fields
+import Proto.Utxorpc.V1beta.Submit.Submit_Fields hiding
+  ( allOf
+  , anyOf
+  , cardano
+  , fieldMask
+  , items
+  , match
+  , maybe'cardano
+  , maybe'chain
+  , maybe'fieldMask
+  , maybe'match
+  , maybe'parsedState
+  , maybe'predicate
+  , nativeBytes
+  , not
+  , predicate
+  , vec'allOf
+  , vec'anyOf
+  , vec'items
+  , vec'not
+  )
 
 type instance RequestMetadata (Protobuf SubmitService meth) = NoMetadata