gRPC: Add searchUtxos method

[carbolymer]

Context

Implements:

• gRPC: UTxORPC searchUtxos method of query service cardano-node#6364

PR upstreaming proto changes:

• Mark optional fields in SearchUtxosRequest with optional utxorpc/spec#194

E2E tests in:

• cardano-testnet | Add searchUtxos gRPC test cardano-node#6553

Checklist

• Commit sequence broadly makes sense and commits have useful messages
• New tests are added if needed and existing tests are updated. See Running tests for more details
• Self-reviewed the diff

[Copilot]

Pull request overview

Adds a new SearchUtxos gRPC endpoint to the cardano-rpc Query service, enabling predicate-based UTxO filtering plus cursor-based pagination, and updates the protobuf schema + generated bindings accordingly.

Changes:

• Introduce server-side predicate matching and SearchUtxos query handling (including address-extraction optimization and cursor pagination).
• Update protobuf definitions to add SearchUtxos and make several fields optional, regenerating Haskell proto-lens bindings and updating wrapper modules.
• Add Hedgehog tests covering predicate semantics and pagination behavior.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cardano-rpc/test/cardano-rpc-test/Test/Cardano/Rpc/Predicate.hs	New property tests for predicate/address/asset matching and address extraction.
cardano-rpc/test/cardano-rpc-test/Test/Cardano/Rpc/Pagination.hs	New property tests for cursor pagination behavior and a multi-digit index regression case.
cardano-rpc/src/Cardano/Rpc/Server/Internal/UtxoRpc/Query.hs	Implements searchUtxosMethod and adds paginateByTxIn.
cardano-rpc/src/Cardano/Rpc/Server/Internal/UtxoRpc/Predicate.hs	New predicate evaluation + address extraction helpers used by SearchUtxos.
cardano-rpc/src/Cardano/Rpc/Server/Internal/Tracing.hs	Adds tracing span constructors/messages for SearchUtxos.
cardano-rpc/src/Cardano/Rpc/Server.hs	Registers SearchUtxos handler in the QueryService method list.
cardano-rpc/src/Cardano/Rpc/Proto/Api/UtxoRpc/Submit.hs	Adjusts re-exported field lenses via hiding to avoid name collisions.
cardano-rpc/src/Cardano/Rpc/Proto/Api/UtxoRpc/Query.hs	Updates wrapper import hiding list due to regenerated fields/methods.
cardano-rpc/proto/utxorpc/v1beta/query/query.proto	Adds SearchUtxos RPC and marks several fields as optional.
cardano-rpc/proto/utxorpc/v1beta/cardano/cardano.proto	Marks Address/Asset/TxOutput pattern fields as optional.
cardano-rpc/gen/Proto/Utxorpc/V1beta/Query/Query_Fields.hs	Regenerated lenses for new optional fields (e.g., maybe'maxItems, maybe'startToken).
cardano-rpc/gen/Proto/Utxorpc/V1beta/Query/Query.hs	Regenerated Query service/messages including searchUtxos and optional field presence.
cardano-rpc/gen/Proto/Utxorpc/V1beta/Cardano/Cardano_Fields.hs	Regenerated lenses for optional pattern fields.
cardano-rpc/gen/Proto/Utxorpc/V1beta/Cardano/Cardano.hs	Regenerated message types to reflect optional fields (record fields now Maybe under the hood).
cardano-rpc/cardano-rpc.cabal	Exposes new predicate module and adds test-suite deps/modules.
.changes/20260423_cardano_rpc_search_utxos.yml	Changelog fragment describing the new RPC and predicate/pagination behavior.

[Copilot]

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]

maxItems is an int32 and can be negative over the wire; currently any maxItems <= 0 silently falls back to the default page size (100). This makes an invalid client value behave like a valid request and can lead to unexpectedly large responses. Consider explicitly rejecting negative maxItems (e.g., return an InvalidArgument-style error) or clamping it to 0/1 with documented semantics.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

[Copilot]

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