Skip to content

gRPC: Add searchUtxos method #1123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
carbolymer merged 1 commit into from
Apr 30, 2026
Merged

gRPC: Add searchUtxos method #1123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changes/20260423_cardano_rpc_search_utxos.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +3 to +6
Copy link

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The changelog fragment is marked only as feature, but this PR changes the public Haskell API generated from the protobufs (e.g., several message fields are now optional, which changes generated record field types to Maybe in exposed cardano-rpc:gen modules, and Cardano.Rpc.Proto.Api.UtxoRpc.Submit now hides previously re-exported field lenses). This should be classified as a breaking change (add breaking to kind: and update the description to call out the specific API surface changes for downstream users).

Copilot generated this review using guidance from repository custom instructions.
6 changes: 6 additions & 0 deletions cardano-rpc/cardano-rpc.cabal
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -130,9 +132,11 @@ test-suite cardano-rpc-test
containers,
hedgehog,
hedgehog-extras,
proto-lens,
rio,
tasty,
tasty-hedgehog,
text,
time,

ghc-options:
Expand All @@ -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
375 changes: 222 additions & 153 deletions cardano-rpc/gen/Proto/Utxorpc/V1beta/Cardano/Cardano.hs
View file
Open in desktop

Large diffs are not rendered by default.

32 changes: 32 additions & 0 deletions cardano-rpc/gen/Proto/Utxorpc/V1beta/Cardano/Cardano_Fields.hs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

288 changes: 177 additions & 111 deletions cardano-rpc/gen/Proto/Utxorpc/V1beta/Query/Query.hs
View file
Open in desktop

Large diffs are not rendered by default.

18 changes: 18 additions & 0 deletions cardano-rpc/gen/Proto/Utxorpc/V1beta/Query/Query_Fields.hs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

14 changes: 7 additions & 7 deletions cardano-rpc/proto/utxorpc/v1beta/cardano/cardano.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
11 changes: 6 additions & 5 deletions cardano-rpc/proto/utxorpc/v1beta/query/query.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion cardano-rpc/src/Cardano/Rpc/Proto/Api/UtxoRpc/Query.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Comment thread
carbolymer marked this conversation as resolved.

type instance RequestMetadata (Protobuf QueryService meth) = NoMetadata

Expand Down
22 changes: 21 additions & 1 deletion cardano-rpc/src/Cardano/Rpc/Proto/Api/UtxoRpc/Submit.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Comment on lines +14 to +34
Copy link

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This module now hides a large set of identifiers from Proto.Utxorpc.V1beta.Submit.Submit_Fields while still re-exporting the module, which removes previously exported field lenses/selectors from the public Cardano.Rpc.Proto.Api.UtxoRpc.Submit API. If this is intentional (to avoid name collisions), it should be called out as a breaking change and ideally documented; otherwise consider not hiding (or re-export under a qualified name) to preserve the existing API surface.

Suggested change
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
)
import Proto.Utxorpc.V1beta.Submit.Submit_Fields

Copilot uses AI. Check for mistakes.

type instance RequestMetadata (Protobuf SubmitService meth) = NoMetadata

Expand Down
1 change: 1 addition & 0 deletions cardano-rpc/src/Cardano/Rpc/Server.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ methodsUtxoRpc
methodsUtxoRpc =
Method (mkNonStreaming $ wrapInSpan TraceRpcQueryParamsSpan . readParamsMethod)
. Method (mkNonStreaming $ wrapInSpan TraceRpcQueryReadUtxosSpan . readUtxosMethod)
. Method (mkNonStreaming $ wrapInSpan TraceRpcQuerySearchUtxosSpan . searchUtxosMethod)
$ NoMoreMethods

methodsUtxoRpcSubmit
Expand Down
4 changes: 4 additions & 0 deletions cardano-rpc/src/Cardano/Rpc/Server/Internal/Tracing.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ data TraceRpcQuery
TraceRpcQueryParamsSpan TraceSpanEvent
| -- | Span trace marking ReadUtxos query
TraceRpcQueryReadUtxosSpan TraceSpanEvent
| -- | Span trace marking SearchUtxos query
TraceRpcQuerySearchUtxosSpan TraceSpanEvent
deriving Show

instance Pretty TraceRpc where
Expand All @@ -53,6 +55,8 @@ instance Pretty TraceRpcQuery where
TraceRpcQueryParamsSpan (SpanEnd _) -> "Finished query params method"
TraceRpcQueryReadUtxosSpan (SpanBegin _) -> "Started query read UTXO method"
TraceRpcQueryReadUtxosSpan (SpanEnd _) -> "Finished query read UTXO method"
TraceRpcQuerySearchUtxosSpan (SpanBegin _) -> "Started query search UTXO method"
TraceRpcQuerySearchUtxosSpan (SpanEnd _) -> "Finished query search UTXO method"

instance Error TraceRpcQuery where
prettyError = pretty
Expand Down
Loading
Loading