Deprecated Feature

Deprecated features and timeline for old feature removals.

NameTypeFirst DeprecatedLast SupportedDescription
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
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
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
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)
....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)
listchannels.include_privateField(s)v24.02v24.08listchannels including private channels (now use listpeerchannels which gives far more detail)
max-locktime-blocksConfigv24.05v24.11--max-locktime-blocks is now set to 2016 in the BOLT 4 spec
commando-runeCommandv23.08v25.02replaced with lightning-createrune
commando-listrunesCommandv23.08v25.02replaced with lightning-showrunes
commando-blacklistCommandv23.08v25.02replaced with lightning-blacklistrune
listpeers.features.option_anchors_zero_fee_htlc_txFieldv24.08v25.08Renamed to option_anchors in the spec: check for that in features instead

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).