Deprecated Feature

Deprecated features and timeline for old feature removals.

NameTypeFirst DeprecatedLast SupportedDescription
delexpiredinvoiceCommandv22.11v24.02autoclean-once is more powerful
autocleaninvoiceCommandv22.11v24.02autoclean is more general, does more than expired invoices
autocleaninvoice-cycleConfigv22.11v24.02Now always once per hour: you can run autoclean-once regularly if you need.
autocleaninvoice-expired-byConfigv22.11v24.02autoclean's autoclean-expiredinvoices-age
feerates.delayed_to_usFieldv23.05v24.02Not used with anchor outputs.
feerates.htlc_resolutionFieldv23.05v24.02Not used with anchor outputs.
listconfigs.configlistFieldsv23.08v24.08Instead of direct members with names equal the config variable, there's now a configs sub-object containing a member with details of each config setting
feerate.NAMEParametersv23.05v23.05Internal (unstable) parameters ("opening", "mutual_close", "delayed_to_us", "htlc_resolution", "penalty", "min_acceptable", "max_acceptable": use new-style names or Nblocks.
invoice_payment_hook.failure_codeHook Returnv22.08v23.02Plugins should generate a complete failure_message for better control
htlc_Accepted_hook.failure_codeHook Returnv0.8v23.02Plugins should generate a complete failure_message for better control
connection_notification.rawfieldsNotification Fieldv23.08v24.08All notifications now wrap members in an object of the same name
disconnection_notification.rawfieldsNotification Fieldv23.08v24.08All notifications now wrap members in an object of the same name
channel_opened.funding_lockedNotification Fieldv22.11v24.02Renamed to channel_ready, as per spec change (zero conf channels are ready before locked)
block_added_notification.blockNotification Fieldv23.08v24.08All notifications now wrap members in an object of the same name
accept-htlc-tlv-typesConfigv23.08v24.08New accept-htlc-tlv-type can be specified multiple times, which is cleaner
bind-addr.torv3Configv23.08v24.08announce-addr makes more sense for Tor addresses
addr.torv3Configv23.08v24.08announce-addr makes more sense for Tor addresses
addr.socketConfigv23.08v24.08bind-addr makes more sense for local sockets since we cannot announce them
experimental-websocket-portConfigv23.08v23.08Use bind=ws: to specify websocket ports on a per-port basis
announce-addr-dnsConfigv23.08v24.08Use bind-addr=dns: to specify DNS announcements on a per-address basis
rest-port.clnrest-prefixConfigv23.11v24.11Autodetect where we need to rename rest-port to clnrest-port (added in v23.11)
rest-protocol.clnrest-prefixConfigv23.11v24.11Autodetect where we need to rename rest-protocol to clnrest-protocol (added in v23.11)
rest-host.clnrest-prefixConfigv23.11v24.11Autodetect where we need to rename rest-host to clnrest-host (added in v23.11)
rest-certs.clnrest-prefixConfigv23.11v24.11Autodetect where we need to rename rest-certs to clnrest-certs (added in v23.11)
sendpay.channel.ignoredParameterv0.12v24.02Ignore channel specified in first hop and simply use peer id and select our own channel.
listpeers.channelsFieldv23.02v24.02Channels are now in listpeerchannels
....0-or-1Configv23.08v24.08Boolean options (in plugins only) used to accept 0 or 1 in place of true or false
options.flag.default-not-falseGetmanifest Replyv23.08v24.08flag options with a default which is not false (would be meaningless, since user can only set it to true
plugin.nonumericidsGetmanifest Replyv23.08v24.08Plugins must specify that they can accept non-numeric command ids (numeric ids are deprecated)
createrune.restrictions.stringParameterv23.05v24.02restrictions parameter must be an array of arrays, not an array of strings
listchannels.include_privateField(s)v24.02v24.08listchannels including private channels (now use listpeerchannels which gives far more detail)
estimatefees.dummy_nullFieldv23.05v24.05deprecated feerates are null (rather than missing) if fee estimate is not available
estimatefees.openingFieldv23.05v24.05opening feerate (implementation-specific, use modern feerates)
estimatefees.mutual_closeFieldv23.05v24.05mutual_close feerate (implementation-specific, use modern feerates)
estimatefees.unilateral_closeFieldv23.05v24.05unilateral_close feerate (implementation-specific, use modern feerates)
estimatefees.delayed_to_usFieldv23.05v24.05delayed_to_us feerate (implementation-specific, use modern feerates)
estimatefees.htlc_resolutionFieldv23.05v24.05htlc_resolution feerate (implementation-specific, use modern feerates)
estimatefees.penaltyFieldv23.05v24.05penalty feerate (implementation-specific, use modern feerates)
estimatefees.min_acceptableFieldv23.05v24.05min_acceptable feerate (implementation-specific, use modern feerates)
estimatefees.max_acceptableFieldv23.05v24.05max_acceptable feerate (implementation-specific, use modern feerates)
commando.missing_idParameterv23.02v24.02Incoming JSON commands without an id field
offer.recurrence_base.at_prefixParameterv24.02v24.05recurrence_base with @ prefix (use recurrence_start_any_period)

Inevitably there are features which need to change: either to be generalized, or removed when they can no longer be supported.

Types of deprecation:

  • Command: an entire command is removed. Usually replaced by a more generic or better-named one.
  • Config: a commandline/configuration option is removed. Usually made the default, or replaced by generalized or better-named.
  • Field(s): a JSON field output. We cannot detect if you are using these, of course.
  • Parameter(s): a JSON RPC input.
  • Getmanifest Reply: a field in the JSON reply which plugins give to getmanifest.
  • Hook Return: a field/value in the JSON reply which plugins give to a plugin hook.
  • Notification Field: a field in the JSON notification to a plugin.

For each deprecation:

  1. The deprecation is listed here, and in the CHANGELOG.md file.
  2. We try to give at least 2 versions before removal.
  3. Then one version where we issue a warning message if we detect a deprecated feature being used (not possible for deprecatred Field types).
  4. At least one version where the deprecated feature can be explicit re-enabled using i-promise-to-fix-broken-api-user=FEATURENAME.

This is designed to minimize the chance that anyone will be surprised by a change!

You can also test earlier. Deprecated features can be disabled in three ways:

  1. developer mode changes the default deprecations to disabled globally.
  2. allow-deprecated-apis= lets you disable (false) or re-enable (true) globally.
  3. The deprecations JSON API can disable/re-enable deprecations for a specific client (added in v24.02).