palladum-lightning/doc/schemas/autoclean-once.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "autoclean-once",
  "title": "A single deletion of old invoices/payments/forwards",
  "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)."
  ],
  "request": {
    "required": [
      "subsystem",
      "age"
    ],
    "additionalProperties": false,
    "properties": {
      "subsystem": {
        "type": "string",
        "enum": [
          "succeededforwards",
          "failedforwards",
          "succeededpays",
          "failedpays",
          "paidinvoices",
          "expiredinvoices",
          "networkevents"
        ],
        "description": [
          "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": {
        "type": "u64",
        "description": [
          "Non-zero number in seconds. How many seconds old an entry must be to delete it."
        ]
      }
    }
  },
  "response": {
    "required": [
      "autoclean"
    ],
    "additionalProperties": false,
    "properties": {
      "autoclean": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "succeededforwards": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "cleaned",
              "uncleaned"
            ],
            "properties": {
              "cleaned": {
                "type": "u64",
                "description": [
                  "The number of successful forwards deleted."
                ]
              },
              "uncleaned": {
                "type": "u64",
                "description": [
                  "The number of successful forwards *not* deleted (too new)."
                ]
              }
            }
          },
          "failedforwards": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "cleaned",
              "uncleaned"
            ],
            "properties": {
              "cleaned": {
                "type": "u64",
                "description": [
                  "The number of failed forwards deleted."
                ]
              },
              "uncleaned": {
                "type": "u64",
                "description": [
                  "The number of failed forwards *not* deleted (too new)."
                ]
              }
            }
          },
          "succeededpays": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "cleaned",
              "uncleaned"
            ],
            "properties": {
              "cleaned": {
                "type": "u64",
                "description": [
                  "The number of successful payments deleted."
                ]
              },
              "uncleaned": {
                "type": "u64",
                "description": [
                  "The number of successful forwards *not* deleted (too new)."
                ]
              }
            }
          },
          "failedpays": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "cleaned",
              "uncleaned"
            ],
            "properties": {
              "cleaned": {
                "type": "u64",
                "description": [
                  "The number of unsuccessful payments deleted."
                ]
              },
              "uncleaned": {
                "type": "u64",
                "description": [
                  "The number of unsuccessful payments *not* deleted (too new)."
                ]
              }
            }
          },
          "paidinvoices": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "cleaned",
              "uncleaned"
            ],
            "properties": {
              "cleaned": {
                "type": "u64",
                "description": [
                  "The number of paid invoices deleted."
                ]
              },
              "uncleaned": {
                "type": "u64",
                "description": [
                  "The number of paid invoices *not* deleted (too new)."
                ]
              }
            }
          },
          "expiredinvoices": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "cleaned",
              "uncleaned"
            ],
            "properties": {
              "cleaned": {
                "type": "u64",
                "description": [
                  "The number of expired invoices deleted."
                ]
              },
              "uncleaned": {
                "type": "u64",
                "description": [
                  "The number of expired invoices *not* deleted (too new)."
                ]
              }
            }
          },
          "networkevents": {
            "type": "object",
            "additionalProperties": false,
            "added": "v25.12",
            "required": [
              "cleaned",
              "uncleaned"
            ],
            "properties": {
              "cleaned": {
                "added": "v25.12",
                "type": "u64",
                "description": [
                  "Total number of deletions done this run."
                ]
              },
              "uncleaned": {
                "added": "v25.12",
                "type": "u64",
                "description": [
                  "The total number of entries *not* deleted this run."
                ]
              }
            }
          }
        }
      }
    }
  },
  "author": [
    "Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
  ],
  "see_also": [
    "lightningd-config(5)",
    "lightning-autoclean-status(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:autoclean-once#1",
        "method": "autoclean-once",
        "params": [
          "failedpays",
          1
        ]
      },
      "response": {
        "autoclean": {
          "failedpays": {
            "cleaned": 0,
            "uncleaned": 7
          }
        }
      }
    },
    {
      "request": {
        "id": "example:autoclean-once#2",
        "method": "autoclean-once",
        "params": [
          "succeededpays",
          1
        ]
      },
      "response": {
        "autoclean": {
          "succeededpays": {
            "cleaned": 7,
            "uncleaned": 0
          }
        }
      }
    }
  ]
}