palladum-lightning/doc/schemas/deldatastore.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "deldatastore",
  "title": "Command for removing (plugin) data",
  "description": [
    "The **deldatastore** RPC command allows plugins to delete data it has stored in the Core Lightning database.",
    "",
    "The command fails if the *key* isn't present, or if *generation* is specified and the generation of the data does not exactly match."
  ],
  "request": {
    "required": [
      "key"
    ],
    "additionalProperties": false,
    "properties": {
      "key": {
        "oneOf": [
          {
            "type": "array",
            "description": [
              "Key is an array of values (though a single value is treated as a one-element array), to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically."
            ],
            "items": {
              "type": "string"
            }
          },
          {
            "type": "string"
          }
        ]
      },
      "generation": {
        "type": "u64",
        "description": [
          "If specified, means that the update will fail if the previously-existing data is not exactly that generation. This allows for simple atomicity. This is only legal with mode `must-replace` or `must-append`."
        ]
      }
    }
  },
  "response": {
    "required": [
      "key"
    ],
    "additionalProperties": false,
    "properties": {
      "key": {
        "type": "array",
        "items": {
          "type": "string",
          "description": [
            "Part of the key added to the datastore."
          ]
        }
      },
      "generation": {
        "type": "u64",
        "description": [
          "The number of times this has been updated."
        ]
      },
      "hex": {
        "type": "hex",
        "description": [
          "The hex data which has removed from the datastore."
        ]
      },
      "string": {
        "type": "string",
        "description": [
          "The data as a string, if it's valid utf-8."
        ]
      }
    }
  },
  "errors": [
    "The following error codes may occur:",
    "",
    "- 1200: the key does not exist",
    "- 1201: the key does exist, but the generation is wrong",
    "- -32602: invalid parameters"
  ],
  "author": [
    "Rusty Russell [rusty@rustcorp.com.au](mailto:rusty@rustcorp.com.au) is mainly responsible."
  ],
  "see_also": [
    "lightning-listdatastore(7)",
    "lightning-datastore(7)",
    "lightning-datastoreusage(7)"
  ],
  "resources": [
    "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
  ],
  "examples": [
    {
      "request": {
        "id": "example:deldatastore#1",
        "method": "deldatastore",
        "params": {
          "key": [
            "test",
            "name"
          ]
        }
      },
      "response": {
        "key": [
          "test",
          "name"
        ],
        "generation": 0,
        "hex": "736176696e67206461746120746f207468652073746f7265",
        "string": "saving data to the store"
      }
    },
    {
      "request": {
        "id": "example:deldatastore#2",
        "method": "deldatastore",
        "params": {
          "key": "otherkey",
          "generation": 1
        }
      },
      "response": {
        "key": [
          "otherkey"
        ],
        "generation": 1,
        "hex": "6f74686572206b65793a207465787420746f20626520617070656e64656420746f20746865206f746865726b6579",
        "string": "other key: text to be appended to the otherkey"
      }
    }
  ]
}