draft: UTXO reservation wallet-side foundations

[mswilkison]

Companion of threshold-network/tbtc-v2#1088 (UTXO reservations: segregated custody with in-kind redemption). A reservation is a deposit the wallet anchors — a 1-input-1-output spend into a fresh wallet-controlled output with no refund path — instead of sweeping, so reserved coins never commingle with the pooled supply and are redeemable in-kind by their owner.

What's included

• Wallet action types for the four lifecycle actions (anchor, reserved redemption, re-anchor, dissolution), appended after the existing enum values to preserve serialized compatibility.
• Coordination proposal types implementing CoordinationProposal, registered in the unmarshaling factory. Marshaling is JSON-based for now with an explicit TODO — switching to protobuf requires adding the reservation message types to the coordination proto definition and regenerating pkg/tbtc/gen/pb.
• Chain interface extensions: GetReservation, ReservationParameters, and the four ValidateReservation*Proposal methods mapping onto the new WalletProposalValidator views from the contracts PR.
• Unsigned transaction assembly for all four lifecycle shapes, enforcing the 1-in-1-out lineage rules the Bridge proves (dissolution additionally spends the wallet main UTXO as its second input, anchor-first, per the Bridge input-order requirement).
• Tests: action parsing, proposal marshaling roundtrips, assembler input validation. go test ./pkg/tbtc/ passes in full.

Deliberately deferred (and why)

1. Ethereum bindings: TbtcChain stubs the new methods with descriptive errors. The generated contract bindings can only be regenerated once the reservation Bridge ABI is published with the @keep-network/tbtc-v2 package — i.e., after the contracts PR merges.
2. Coordination executor wiring + tbtcpg proposal generation: both consume the bindings above, so they land in the same follow-up. The assembly and validation layers they will call are what this PR provides.
3. Protobuf marshaling for the proposal types (see TODO markers).

Note for maintainers

origin/main currently fails to build (pkg/tbtcpg/redemptions.go:225: the Chain interface was refactored to return tbtc.RedemptionParameters as a struct, but the fee-estimation call site still destructured the old 8-value tuple) — the Client workflow is red on the main tip as well. This PR carries the one-line repair as a separate labeled commit so CI can run green here; feel free to cherry-pick it to main independently of the reservation work.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b2b9b1d9-f71d-416d-906a-670fa1d91985

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}