core-lightning/doc/schemas/lightning-bkpr-inspect.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "bkpr-inspect",
  "title": "Command to show onchain footprint of a channel",
  "description": [
    "The **bkpr-inspect** RPC command lists all known on-chain transactions and associated events for the provided account. Useful for inspecting unilateral closes for a given channel account. Only valid for channel accounts."
  ],
  "request": {
    "required": [
      "account"
    ],
    "additionalProperties": false,
    "properties": {
      "account": {
        "type": "string",
        "description": [
          "Channel account to inspect."
        ]
      }
    }
  },
  "response": {
    "required": [
      "txs"
    ],
    "additionalProperties": false,
    "properties": {
      "txs": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "txid",
            "fees_paid_msat",
            "outputs"
          ],
          "properties": {
            "txid": {
              "type": "txid",
              "description": [
                "Transaction id."
              ]
            },
            "blockheight": {
              "type": "u32",
              "description": [
                "Blockheight of transaction."
              ]
            },
            "fees_paid_msat": {
              "type": "msat",
              "description": [
                "Amount paid in sats for this tx."
              ]
            },
            "outputs": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "account",
                  "outnum",
                  "output_value_msat",
                  "currency"
                ],
                "additionalProperties": false,
                "properties": {
                  "account": {
                    "type": "string",
                    "description": [
                      "Account this output affected."
                    ]
                  },
                  "outnum": {
                    "type": "u32",
                    "description": [
                      "Index of output."
                    ]
                  },
                  "output_value_msat": {
                    "type": "msat",
                    "description": [
                      "Value of the output."
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "description": [
                      "Human-readable bech32 part for this coin type."
                    ]
                  },
                  "credit_msat": {
                    "type": "msat",
                    "description": [
                      "Amount credited to account."
                    ]
                  },
                  "debit_msat": {
                    "type": "msat",
                    "description": [
                      "Amount debited from account."
                    ]
                  },
                  "originating_account": {
                    "type": "string",
                    "description": [
                      "Account this output originated from."
                    ]
                  },
                  "output_tag": {
                    "type": "string",
                    "description": [
                      "Description of output creation event."
                    ]
                  },
                  "spend_tag": {
                    "type": "string",
                    "description": [
                      "Description of output spend event."
                    ]
                  },
                  "spending_txid": {
                    "type": "txid",
                    "description": [
                      "Transaction this output was spent in."
                    ]
                  },
                  "payment_id": {
                    "type": "hex",
                    "description": [
                      "Lightning payment identifier. For an htlc, this will be the preimage."
                    ]
                  }
                },
                "allOf": [
                  {
                    "if": {
                      "required": [
                        "credit_msat"
                      ]
                    },
                    "then": {
                      "required": [
                        "output_tag"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "account": {},
                        "outnum": {},
                        "output_value_msat": {},
                        "currency": {},
                        "credit_msat": {},
                        "originating_account": {},
                        "debit_msat": {},
                        "output_tag": {},
                        "spend_tag": {},
                        "spending_txid": {},
                        "payment_id": {}
                      }
                    }
                  },
                  {
                    "if": {
                      "required": [
                        "spending_txid"
                      ]
                    },
                    "then": {
                      "required": [
                        "spend_tag",
                        "debit_msat"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "account": {},
                        "outnum": {},
                        "output_value_msat": {},
                        "currency": {},
                        "credit_msat": {},
                        "originating_account": {},
                        "debit_msat": {},
                        "output_tag": {},
                        "spend_tag": {},
                        "spending_txid": {},
                        "payment_id": {}
                      }
                    }
                  }
                ]
              }
            }
          }
        }
      }
    }
  },
  "author": [
    "Lisa Neigut <<niftynei@gmail.com>> is mainly responsible."
  ],
  "see_also": [
    "lightning-listbalances(7)",
    "lightning-listfunds(7)",
    "lightning-listpeers(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:bkpr-inspect#1",
        "method": "bkpr-inspect",
        "params": {
          "account": "a397dd9b3e44afcb67f3f3ce1d649b74a8ade63e35505985e4cc1828634f69a2"
        }
      },
      "response": {
        "txs": [
          {
            "txid": "cd23f0517eefc27194981253eb07b19b055246df77033e052c66eaf2bbb00483",
            "blockheight": 111,
            "fees_paid_msat": 4927000,
            "outputs": [
              {
                "account": "a397dd9b3e44afcb67f3f3ce1d649b74a8ade63e35505985e4cc1828634f69a2",
                "outnum": 0,
                "output_tag": "channel_open",
                "output_value_msat": 1000000000,
                "credit_msat": 1000000000,
                "currency": "bcrt",
                "spend_tag": "channel_close",
                "spending_txid": "70e0466dc2e74f25afe38df6a85d5e8857079873a6d5eda4732806a7ac427305",
                "debit_msat": 489818898
              }
            ]
          },
          {
            "txid": "70e0466dc2e74f25afe38df6a85d5e8857079873a6d5eda4732806a7ac427305",
            "blockheight": 121,
            "fees_paid_msat": 2895898,
            "outputs": [
              {
                "account": "wallet",
                "outnum": 0,
                "output_tag": "deposit",
                "output_value_msat": 486923000,
                "credit_msat": 486923000,
                "currency": "bcrt"
              },
              {
                "account": "external",
                "outnum": 1,
                "output_tag": "to_them",
                "output_value_msat": 510181000,
                "credit_msat": 510181000,
                "currency": "bcrt",
                "originating_account": "a397dd9b3e44afcb67f3f3ce1d649b74a8ade63e35505985e4cc1828634f69a2"
              }
            ]
          }
        ]
      }
    }
  ]
}