Skip to content

Mark optional fields in SearchUtxosRequest with optional#194

Open
carbolymer wants to merge 1 commit intoutxorpc:mainfrom
carbolymer:add-optional-fields-to-git
Open

Mark optional fields in SearchUtxosRequest with optional#194
carbolymer wants to merge 1 commit intoutxorpc:mainfrom
carbolymer:add-optional-fields-to-git

Conversation

@carbolymer
Copy link
Copy Markdown
Contributor

@carbolymer carbolymer commented Mar 17, 2026

Motivation

In proto3, fields without the optional keyword are not given presence tracking.
An empty bytes field and one that was never set are represented identically on the wire and in generated code.
As a result, "the client left this filter blank" cannot be distinguished from "the client wants to match on empty bytes" by the server, and "no more pages" cannot be distinguished from "an empty token was set" by the client.

The SearchUtxos predicate hierarchy is built on combining address patterns, asset patterns and boolean operators.
Each pattern field is intended as a filter: when present it should constrain the result set, and when absent it should be ignored.
Without optional, the proto3 default (empty bytes, zero, empty string) must be treated as "absent" by implementations.
This convention is fragile and cannot be enforced by the encoding itself.

With optional, fields are represented with presence-aware types in generated code (e.g. Maybe in Haskell, has_ checks in other languages), so the "absent vs default" distinction is handled naturally rather than through ad-hoc empty checks.

Changes

The following fields are marked as optional to enable presence semantics:

  • AddressPattern: exact_address, payment_part, delegation_part
  • AssetPattern: policy_id, asset_name
  • TxOutputPattern: address, asset
  • UtxoPredicate: match
  • SearchUtxosRequest: predicate, max_items, start_token
  • SearchUtxosResponse: next_token

Wire compatibility

The wire encoding is not changed by adding optional to scalar and message fields.
Existing clients and servers that treat default values as absent are not affected.

@carbolymer carbolymer marked this pull request as draft March 17, 2026 20:21
@carbolymer carbolymer force-pushed the add-optional-fields-to-git branch 2 times, most recently from cdebf78 to 8ec8f95 Compare April 28, 2026 09:02
@carbolymer carbolymer force-pushed the add-optional-fields-to-git branch from 8ec8f95 to 563fbdd Compare April 30, 2026 09:35
@carbolymer carbolymer marked this pull request as ready for review April 30, 2026 09:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants