autoclean-once -- A single deletion of old invoices/payments/forwards

SYNOPSIS

autoclean-once subsystem age

DESCRIPTION

The autoclean-once RPC command tell the autoclean plugin to do a single sweep to delete old entries. This is a manual alternative (or addition) to the various autoclean-...-age parameters which cause autoclean to run once per hour: see lightningd-config(5).

• subsystem (string) (one of "succeededforwards", "failedforwards", "succeededpays", "failedpays", "paidinvoices", "expiredinvoices", "networkevents"): What subsystem to clean. Currently supported subsystems are:
  • failedforwards: routed payments which did not succeed (failed or local_failed in listforwards status).
  • succeededforwards: routed payments which succeeded (settled in listforwards status).
  • failedpays: payment attempts which did not succeed (failed in listpays status).
  • succeededpays: payment attempts which succeeded (complete in listpays status).
  • expiredinvoices: invoices which were not paid (and cannot be) (expired in listinvoices status).
  • paidinvoices: invoices which were paid (paid in listinvoices `status).
  • networkevents: all events in listnetworkevents (added v25.12)

NOTE: until v25.12, the uncleaned field contained all entries not removed (e.g. in `failedforwards it counted all forwards, not just failed ones). This was an interface only an engineer could love, so it was fixed.

• age (u64): Non-zero number in seconds. How many seconds old an entry must be to delete it.

RETURN VALUE

On success, an object containing autoclean is returned. It is an object containing:

• succeededforwards (object, optional):
  • cleaned (u64): The number of successful forwards deleted.
  • uncleaned (u64): The number of successful forwards not deleted (too new).
• failedforwards (object, optional):
  • cleaned (u64): The number of failed forwards deleted.
  • uncleaned (u64): The number of failed forwards not deleted (too new).
• succeededpays (object, optional):
  • cleaned (u64): The number of successful payments deleted.
  • uncleaned (u64): The number of successful forwards not deleted (too new).
• failedpays (object, optional):
  • cleaned (u64): The number of unsuccessful payments deleted.
  • uncleaned (u64): The number of unsuccessful payments not deleted (too new).
• paidinvoices (object, optional):
  • cleaned (u64): The number of paid invoices deleted.
  • uncleaned (u64): The number of paid invoices not deleted (too new).
• expiredinvoices (object, optional):
  • cleaned (u64): The number of expired invoices deleted.
  • uncleaned (u64): The number of expired invoices not deleted (too new).
• networkevents (object, optional) (added v25.12):
  • cleaned (u64): Total number of deletions done this run. (added v25.12)
  • uncleaned (u64): The total number of entries not deleted this run. (added v25.12)

AUTHOR

Rusty Russell [email protected] is mainly responsible.

SEE ALSO

lightningd-config(5), lightning-autoclean-status(7)

RESOURCES

Main web site: https://github.com/ElementsProject/lightning

EXAMPLES

Example 1:

Request:

lightning-cli autoclean-once "failedpays" "1"

{
  "id": "example:autoclean-once#1",
  "method": "autoclean-once",
  "params": [
    "failedpays",
    1
  ]
}

Response:

{
  "autoclean": {
    "failedpays": {
      "cleaned": 0,
      "uncleaned": 7
    }
  }
}

Example 2:

Request:

lightning-cli autoclean-once "succeededpays" "1"

{
  "id": "example:autoclean-once#2",
  "method": "autoclean-once",
  "params": [
    "succeededpays",
    1
  ]
}

Response:

{
  "autoclean": {
    "succeededpays": {
      "cleaned": 7,
      "uncleaned": 0
    }
  }
}