Changelog

Changes to the .proto definitions, newest first. Dates are the dates the change landed in the canonical proto source.

The proto files served from /proto and the per-service docs on this site track these changes. The auto-generated API Reference lags until it is regenerated — when in doubt, the live rpc.discover method on a running Hydra App is authoritative.

2026-07-08 — Archive-prune redesign (breaking)

App — the synchronous PruneArchive RPC was removed and replaced by an asynchronous job model. PruneArchive / PruneArchiveRequest / PruneArchiveResponse (with total_pruned / per_table) no longer exist.

New RPCs:

• StartArchivePrune — starts (or attaches to) the prune job for a network; returns an ArchivePruneJob descriptor + newly_started. At most one job runs per network. Filters (max_age_secs, max_items) moved into ArchivePruneParams; at least one must be set and max_items must be ≥ 1.
• GetArchivePruneStatus — the authoritative state: the currently running job (with an ArchivePruneProgress snapshot) and the last finished ArchivePruneRecord.
• CancelArchivePrune — requests cancellation (asynchronous; stops at the next chunk boundary). Idempotent.
• SubscribeArchivePruneEvents — a stream of ArchivePruneEvent (started / progress / completed / failed / cancelled) across all networks. Best-effort delivery — reconcile with GetArchivePruneStatus on stream end.

Config also gained an optional settings.auto_prune block (periodic auto-prune). Pruning a settled payment still deletes its stored preimage, so GetPreimage stops serving pruned payments. See General API → Archive Prune.

Action required: replace any PruneArchive / app_pruneArchive call with StartArchivePrune + a poll of GetArchivePruneStatus (or a SubscribeArchivePruneEvents subscription).

App (invite / referral) — three new RPCs: CreateInvite (mint a bearer invite code), RedeemInvite (redeem a peer's code; returns the inviter's public key), and GetReferral (the currently configured referrer, if any). A new config.yaml referral_config.referral_service_url wires the referral service.

2026-07-06 — HTLC lock types

HTLC — the on-chain HTLC RPCs gained a lock_type field (canonical protocol-defined script-kind token, e.g. Bitcoin "taproot" / "p2wsh"; empty = the node's signer-derived default). It appears on CreateHtlcRequest, CreateHtlcLockTxRequest, DeriveHtlcAddressRequest, BatchCreateHtlcsRequest, and — as a required-match pin on the receiving side — HtlcExpectation.lock_type. A config.yaml htlc_factory_address (EVM) and htlc_script_type knob gate on-chain HTLC availability.

2026-07-02 — HTLC event handling refactor + transaction HTLC operations (breaking)

Event — the 2026-06-04 NodeEvent.HtlcUpdate / HtlcSnapshot design was replaced. NodeEvent no longer carries an HTLC variant. Instead EventService gained a dedicated stream SubscribeHtlcEvents(SubscribeHtlcEventsRequest{ network }) → stream Htlc: it emits the full Htlc on every lifecycle transition, and the HTLC's status (Locked / Claimed / Refunded) conveys what happened — Claimed reveals the preimage. Dedupe key: (htlc-id, status).

If you subscribed to NodeEvent for HtlcUpdate (added 2026-06-04), switch to SubscribeHtlcEvents. The HtlcSnapshot message is gone; use Htlc.

Transaction — TransactionOperation gained repeated HtlcOperation htlc_operations (field 13): on-chain HTLC lock / claim / refund operations observed within a wallet transaction (HtlcLock / HtlcClaim — reveals the preimage — / HtlcRefund). TransactionRequest.raw_data was renamed to signable_data with a documented per-protocol encoding (EVM: UTF-8 JSON eth_sendTransaction params; Bitcoin: base64 PSBT); SignedTransactionRequest documents its broadcastable encoding likewise.

2026-06-24 — On-chain HTLC swap milestones

Swap — SimpleSwapUpdate.update (the SubscribeSimpleSwaps stream) gained seven on-chain-settlement milestone variants (fields 27–33): locking_onchain_htlc, onchain_htlc_locked, counterparty_lock_confirming ({ txid, current, required }), counterparty_lock_observed, claiming_onchain_htlc, onchain_htlc_claimed, refunding_onchain_htlc. They appear when a swap leg settles on-chain rather than through a channel (see the settlement model). Existing channel-path milestones are unchanged; add branches for the new variants only if you render on-chain progress.

2026-06-17 — Redeemable channel balances + unique HTLC keys

Balance — AssetChannelBalance gained redeemable_local and redeemable_remote (fields 11–12): the local/remote amounts redeemable on-chain when the channel is redeemable (zero otherwise). These are a view into unavailable_local / unavailable_remote, not additional balance categories — don't double-count.

HTLC — new RPC GetUniqueHtlcPubkey: reserves a fresh HTLC public key (UTXO protocols return a never-before-used key per call; account-model protocols return their single stable key). GetHtlcPubkey returns the node's canonical key.

2026-06-16 — Signer: sign-and-broadcast

Signer — new RPC SignAndBroadcastTx: signs (or authorizes) an unsigned transaction and ensures it reaches the chain, returning the txid. The universal path — an offline signer signs and the client broadcasts, or a self-broadcasting authority (e.g. MetaMask) signs and broadcasts in one step. SignTransactionResponse.signed_tx changed from a structured SignedTransactionRequest to serialized bytes (ready to broadcast); SignTransaction now fails for broadcast-only signers that can't produce standalone signed bytes — use SignAndBroadcastTx for those.

2026-06-15 — Orderbook on-chain settlement wiring

Orderbook — the swap-routing messages gained on-chain-settlement plumbing:

• SwapHop gained optional sending_onchain (OnchainSendSettlement) and receiving_onchain (OnchainRecvSettlement) — unset means channel settlement (the default). New TimelockSpec (absolute block-height / unix-seconds) mirrors the route's on-chain HTLC timelock.
• SwapPath (in MatchedOrder) gained settlement (OrderSettlement) per leg. On-chain is valid only for taker (market/swap) orders; resting maker orders are channel-only.
• ORDER_TYPE_LIQUIDITY (2) is a real enum value (previously an internal-reserved slot).

2026-06-11 — Preimage service, order settlement & HTLC service rework (breaking)

A large change introducing hybrid (channel + on-chain) swap settlement.

Preimage — a new top-level PreimageService (JSON-RPC namespace preimage) with one RPC SettlePreimage(network, payment_preimage): registers a revealed preimage and settles every leg it unlocks — held channel hashlock payments (claim + arm force-close) and, on HTLC-capable networks, matching on-chain HTLCs. NodeService.RegisterPreimage was removed — its behavior is now SettlePreimage (which additionally claims on-chain HTLCs).

Action required: replace node.RegisterPreimage with preimage.SettlePreimage. Request fields are identical (network, hex payment_preimage). See the new HTLC & Preimage API.

Currency — new LegSettlement enum (CHANNEL (0, default) / ONCHAIN (1) / CHANNEL_OR_ONCHAIN (2)) and OrderSettlement message (sending / receiving LegSettlement + taker-only route_filter bitmask). Absent = channel on both legs.

Swap — SwapRequest gained settlement (OrderSettlement) (field 4); the orderbook OrderVariant / SwapOrder creation paths accept per-leg settlement. Absent keeps the previous channel-only behavior.

Orderbook — breaking — add_liquidity was removed from CreateOrder's OrderVariant oneof. The creatable variants are now limit_order, market_order, swap_order only. Provide passive / maker liquidity by placing limit orders. The LiquidityOrder message and ORDER_TYPE_LIQUIDITY remain as the persisted / returned form (PairOrder.liquidity_order) for positions created that way; you can still read, hold, and cancel them.

Action required: delete any CreateOrder { order_variant: { add_liquidity: … } } path. Replace range provision (min_buy_price / mid_price / max_sell_price / remove_on_fill) with one or more limit orders.

HTLC — HtlcService (namespace htlc) was reworked from a stub into a full on-chain HTLC surface: external-signer transaction builders (CreateHtlcLockTx / CreateHtlcClaimTx / CreateHtlcRefundTx / CreateHtlcSettlementTx / BroadcastHtlcSettlement), GetChainHtlc, VerifyHtlcByLockTxid, DeriveHtlcAddress, WatchHtlc / UnwatchHtlc, GetHtlcPubkey. The old HtlcState / HtlcStatus-enum / HtlcEvent shapes were replaced by a unified Htlc message (chain-native id, display-unit amount, Timelock + LedgerDepth with explicit kind, and a HtlcStatus oneof { Locked | Claimed | Refunded }). Amounts are now in the asset's display unit and timelocks are absolute (Unix-seconds / block-height), not block counts. See the HTLC & Preimage API.

2026-06-04 — HTLC update events (superseded 2026-07-02)

Superseded. This NodeEvent.HtlcUpdate / HtlcSnapshot design was replaced on 2026-07-02 by the dedicated EventService.SubscribeHtlcEvents stream, which emits the full Htlc. Kept here for history; do not build against HtlcUpdate or HtlcSnapshot.

Event — NodeEvent.update gained a new variant HtlcUpdate { HtlcSnapshot htlc } (field 15). The HtlcSnapshot carries protocol-agnostic on-chain HTLC state: identifier, asset, amount, payment hash, recipient / refund addresses, absolute expiry, lock txid + block height, and a oneof status { Locked | Claimed | Refunded }. Claimed status reveals the preimage — critical for atomic-swap takers waiting on the maker's claim. Dedupe key: (htlc.htlc_id, status).

2026-06-03 — EstimateSimpleSwappableAmounts response now non-optional

Swap — EstimateSimpleSwappableAmountsResponse.amounts changed from optional SimpleSwappableAmounts to always-present SimpleSwappableAmounts. When no feasible swap exists, all four fields collapse to "0" rather than the field being absent. Bots that branched on "amounts field unset → no liquidity" must switch to "max_sending == "0" → no swap currently feasible."

2026-05-26 — Archive retention (redesigned 2026-07-08)

Superseded. The synchronous PruneArchive introduced here was replaced on 2026-07-08 by the asynchronous StartArchivePrune job model. Kept for history.

App — new RPC PruneArchive: operator-driven retention. Prunes archive-side settled wallet transactions and settled payments for one network, filtered by max age and/or max count. Pending entries are never pruned. With both filters unset the call is a no-op.

See General API → Archive Prune for the current shape.

2026-05-21 — Node policy introspection

Node — new read-only RPC GetNodePolicy for one (network, asset_id). The response is an aggregate of policy sub-messages; the first category exposed is ReservePolicy (channel reserve parameters: counterparty proportional rate in millionths, max self proportional rate in millionths, absolute minimum, and a fixed channel-reserve fee). Liquidity providers and any party sizing on-chain deposits accurately should call this before negotiating a channel.

New sub-messages will be added in a backwards-compatible way as more NodeConfig categories are exposed — treat each as optional.

See Node API → Get Node Policy.

2026-05-19

Swap — counterparty invoice-window handling and convergence retry in the simple-swap flow (server-side behavior; no request/response shape change for clients).

2026-05-10 — Payment timing (CLTV) overhaul

Breaking field renames on the Node API payment RPCs. If you send keysend payments or create invoices, update your code.

Node

• SendChannelPaymentRequest: expiry_timeout_secs → cltv_buffer_secs. (KeySend has no separate invoice-validity knob; the buffer alone bounds the HTLC.)
• EstimateSendPaymentFeeRequest: expiry_timeout_secs → cltv_buffer_secs; new optional max_total_cltv_secs (clamp the route's max-total-CLTV; for atomic-swap-correct timing pass the invoice's cltv_buffer_secs, otherwise omit).
• SendPaymentRequest: same change as EstimateSendPaymentFeeRequest.
• CreateInvoiceRequest: expiry_timeout_secs keeps its meaning (BOLT-11 x — invoice validity window) and gains a new optional cltv_buffer_secs (BOLT-11 c — extra HTLC lifetime past invoice expiry the receiver requires).
• EstimatePayInvoiceFeeRequest, PayInvoiceRequest, EstimatePayEmptyInvoiceFeeRequest, PayEmptyInvoiceRequest: new optional max_total_cltv_secs.

Payment

• Invoice: new field min_final_cltv_expiry_secs — the minimum CLTV buffer (seconds) the receiver requires for the incoming HTLC. The HTLC's effective deadline is expiry_timestamp + min_final_cltv_expiry_secs.

2026-05-06 — Lease API: read-only discovery

Liquidity — four new read-only RPCs (no funds move):

• GetLiquidityServiceInfo — server-wide capacity bounds, durations, per-asset fee config, and the LP's per-network node pubkeys.
• GetLeaseableAssetInfo — per-asset liquidity bounds + fee ratio for one (network, asset).
• GetLeases — the caller's active leases on a network.
• GetLeaseExpiries — lease expiry per (channel_id, asset_id) from the local cache (no LP round-trip).

Also: ChannelReleaseOperation.CooperativeClose gained asset_ids — empty closes every asset channel; otherwise only the listed ones.

2026-05-05 — Lease API: tx_fee_rate removed (breaking)

Liquidity / Swap — the liquidity service now prices the underlying transaction work itself. The client no longer supplies a chain fee rate.

• RequestChannelLiquidityRequest: removed tx_fee_rate (remaining fields renumbered).
• RequestChannelReleaseRequest: removed tx_fee_rate (remaining fields renumbered).
• ReceivingChannelLease (swap): removed tx_fee_rate (remaining fields renumbered).

Action required: delete tx_fee_rate / txFeeRate / TxFeeRate from any Lease request you build. Sending it now returns -32602 unknown field 'txFeeRate'. The Lease API examples have been updated.

2026-05-03 — Channel close flag + client order IDs

Channel

• AssetChannelStatus.Closed gained force_closed (bool). false = cooperative close (in lithium the channel slot can be reused for further deposits); true = unilateral / disputed close (slot is permanently dead — open a new channel).

Orderbook

• CreateOrderRequest gained optional client_order_id (max 64 chars). When set and unique among your open orders, the orderbook stores it, returns the original order_id on retries with the same value (idempotent order creation), and exposes it on subsequent reads.
• Order gained optional client_order_id.
• New RPC GetOrderByClientId — fetch an order by the client_order_id you supplied at creation.
• SwapRole enum reordered: SWAP_ROLE_TAKER moved from 0 to 3. SWAP_ROLE_UNSPECIFIED is 0. If you persisted raw enum integers, re-map them.

2026-04-29 — Swappable-amount estimation

Swap — new RPC EstimateSimpleSwappableAmounts: given two currencies, returns the smallest and largest amounts that can currently be simple-swapped, accounting for wallet balances, orderbook liquidity, and the LP's leaseable capacity. Returns an empty amounts field when the pair has no orderbook liquidity; all-zero fields when the pair has liquidity but no swap is currently feasible.

2026-04-27 — New SimpleSwap estimate variant

Swap — SimpleSwapEstimate gained the InsufficientSendingBalance variant ({ available: DecimalString }). Distinct from NoLiquidity: the market is fine, but the wallet has nothing to send (no active channel and no usable on-chain funds after fees). If you match/switch on the estimate one-of, add a branch for it.

Earlier

The 2026-04 reconciliation aligned every doc with the then-current proto, including the rename of the old RentalService to LiquidityService (the Lease API). The rental_* JSON-RPC namespace no longer exists — it is liquidity_*. See the Lease API.

How this list is maintained

Each entry corresponds to a proto-touching commit in the Hydra App source. When the protos in /proto are refreshed, this page and the affected per-service docs are updated together. The single source of truth for a running server is its rpc.discover output — see JSON-RPC: Discovering methods.