[hieblmi]

What this adds

This PR lets a client buy and manage an asset reservation before starting a
swap. A reservation sets aside a fixed asset amount in an on-chain output
for that client, for a limited time. Spending uses a shared client/server key;
a timeout path allows unused funds to be reclaimed.

A buyer selects either an exact asset ID or a compressed, tweaked group key. An exact request requires that issuance both on chain and on the receiving channel. A group request allows different fungible issuances for the two legs. The quote identifies both; loopd verifies the anchor and member issuance proofs before it probes or pays. The buyer approves those exact terms, and delivery must prove the quoted funding issuance.

The client pays the quoted service fee upfront to obtain the reservation.
The asset principal is paid for later, when the client executes the swap.
Under this contract, the prepayment covers the later swap's service fee and
is credited once. Routing and miner fees are separate, and the prepayment is
not refunded if the reservation goes unused.

The purchase flow validates and saves a quote, sends one full-amount asset
hold probe through SendPaymentV2, asks for approval, pays the BTC prepay
invoice, and verifies delivery before marking the reservation Ready.
The server validates the accepted asset HTLC and saves its receipt before
canceling the probe invoice. Success requires that receipt, server cancellation,
and a failed local payment with FAILURE_REASON_INCORRECT_PAYMENT_DETAILS.
Success does not depend on LND retaining failed HTLC attempts.

Each purchase has one quote and one probe payment. Failed probes cancel the
unpaid purchase; another attempt requires a fresh reservation ID, optionally
with --skip_probe. Recovery resumes the saved payment or finishes cancellation.
The probe checks current liquidity without reserving it for the later swap.
The client captures route fees from live SendPaymentV2 updates and resumes
observation through TrackPaymentV2. The prepay estimate scales the observed
route fee by the invoice amounts. If recovery misses the route before LND
prunes it, the probe can still succeed with unavailable fee estimates;
probe_fee_known distinguishes missing data from an observed zero fee.

Purchase flow

flowchart TD
    Q["RequestQuote: request and validate a quote<br/>Save the purchase ID, keys, and agreed terms"]
    P["ProbeRoutes: send the full-amount hold probe<br/>Verify receipt and cancellation"]
    A["AwaitApproval: show the quote and probe result"]
    PAY["PayPrepay: save payment intent<br/>Pay and track the BTC prepay invoice"]
    WAIT["WaitForDelivery: obtain the funding outpoint and asset proof"]
    VERIFY["VerifyReservation: check the asset, amount, keys, proof,<br/>confirmations, and remaining lifetime"]
    READY["Ready: verified reservation available for a later swap"]
    CANCEL["CancelPrepay: resolve any payment before cancellation"]
    CANCELED["Canceled"]

    Q --> P
    Q -->|Explicit --skip_probe| A
    P -->|Verified receipt and resolved payment| A
    P -->|Probe failed| CANCEL
    A -->|Approve exact quote and routing cap| PAY
    A -->|Cancel or quote expires| CANCEL
    PAY -->|Payment settled| WAIT
    WAIT --> VERIFY
    VERIFY -->|Checks pass| READY
    CANCEL -->|Unpaid cancellation confirmed| CANCELED
    CANCEL -->|Payment settled instead| WAIT

Loading

Normal approval requires a successful main-payment probe. --skip_probe
explicitly permits purchase without one; quote validation and payment limits
still apply. Declining the prompt leaves the purchase saved and unpaid.

The daemon saves progress throughout the purchase and resumes unfinished work
after a restart. It records the exact payment before sending and resolves an
uncertain result by tracking that payment. Delivery is verified locally, and
ready reservations remain monitored for spending and expiry. Recovery retains
the original lifetime rather than starting a new clock.

Using the reservation in a swap

A later asset Loop Out will select the funded reservation by its txid:vout,
check that enough time remains, and obtain a fresh execution quote. The client
will pay the main Lightning invoice to receive the reserved assets on-chain
through the swap protocol. The saved prepay credit avoids charging the service
fee twice; the BTC-to-asset conversion price can change before execution and
requires fresh approval.

This PR implements reservation purchase through Ready. Executing the later
asset swap is follow-up work. It includes persistent terms and state history,
payment recovery, proof and confirmation checks, authenticated RPCs, and
loop asset reservation buy, list, and get. Purchases
require --experimental and a configured tapd.

Extending this to BTC reservations

The same quote, approval, prepay, recovery, and readiness flow can support BTC
reservations. A follow-up would add BTC-denominated terms and a Bitcoin funding
verifier in place of asset proofs and conversion checks, then connect ready
reservations to Instant Out. BTC reservation purchases are not enabled here.

Earlier work and dependency

This replaces the reservation-buying approach in
#883 and
#1195.

The branch stacks on Loop #1225 at 0ad07d71c and uses tap-sdk v0.1.1 with Taproot Assets v0.8.8 and the TLV decoder from that tag. Purchases retain their negotiated, server-funded CSV contract. The shared deposit constructor supplies the anchor and refund leaf, and the kit ties the agreed terms to an isolated asset commitment. New on-chain reservations require a running tapd v0.8.8 or later. The server integration is Nautilus #1730.

The paying node can retry a transient identity lookup before probe dispatch until the original quote expires. If local verification invalidates a delivered proof after a reorg, the client retains the delivery record, leaves Ready and withdraws proof verification and execution deadlines.

Validation

Before this minimum-version update, the full Loop unit suite, affected race suites, lint and module tidy checks passed. The real-node purchase case exercised quote, probe, held prepay, funding, client/server restart, bound proof acceptance, cancellation and the CSV refund.

At the new tapd v0.8.8 minimum, the policy, swapkit, reservation and loopd unit tests pass. The boundary tests cover both the released daemon and rejected older nodes. The v0.8.8 release fixes a regression that could prevent asset invoices from settling. Taproot Assets v0.8.8 release notes

Pull Request Checklist

• Added entries to docs/release-notes/release-notes-next.md.