core-lightning/doc/schemas/lightning-splice_init.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "added": "v23.08",
  "rpc": "splice_init",
  "title": "Command to initiate a channel to a peer",
  "warning": "experimental-splicing only",
  "description": [
    "`splice_init` is a low level RPC command which initiates a channel splice for a given channel specified by `channel_id`."
  ],
  "request": {
    "required": [
      "channel_id",
      "relative_amount"
    ],
    "properties": {
      "channel_id": {
        "type": "hash",
        "description": [
          "The channel id of the channel to be spliced."
        ]
      },
      "relative_amount": {
        "type": "integer",
        "description": [
          "A positive or negative amount of satoshis to add or subtract from the channel. Note you may need to add a double dash (--) after splice_init if using a negative *relative_amount* so it is not interpretted as a command modifier. For example: ```shell lightning-cli splice_init -- $CHANNEL_ID -100000 ```."
        ]
      },
      "initialpsbt": {
        "type": "string",
        "description": [
          "The (optional) base 64 encoded PSBT to begin with. If not specified, one will be generated automatically."
        ]
      },
      "feerate_per_kw": {
        "type": "u32",
        "description": [
          "The miner fee we promise our peer to pay for our side of the splice transaction. It is calculated by `feerate_per_kw` * our_bytes_in_splice_tx / 1000."
        ]
      },
      "force_feerate": {
        "type": "boolean",
        "description": [
          "By default splices will fail if the fee provided looks too high. This is to protect against accidentally setting your fee higher than intended. Set `force_feerate` to true to skip this saftey check."
        ]
      }
    }
  },
  "response": {
    "required": [
      "psbt"
    ],
    "properties": {
      "psbt": {
        "type": "string",
        "description": [
          "The (incomplete) PSBT of the splice transaction."
        ]
      }
    }
  },
  "usage": [
    "Here is an example set of splice commands that will splice in 100,000 sats to the first channel that comes out of `listpeerchannels`.",
    "",
    "The example assumes you already have at least one confirmed channel.",
    "",
    "1: Get the channel id of the first channel.",
    "",
    "```shell",
    "CHANNEL_ID=$(echo $(lightning-cli listpeerchannels) | jq -r \".channels[0].channel_id\")",
    "```",
    "2: Get the PSBT from fundpsbt.",
    "",
    "```shell",
    "INITIALPSBT=$(echo $(lightning-cli fundpsbt -k satoshi=100000sat feerate=urgent startweight=800 excess_as_change=true) | jq -r \".psbt\")",
    "```",
    "3: Initiate the splice by passing channel id and initialpsbt received from above steps.",
    "",
    "```shell",
    "PSBT_SPLICE_INIT=$(echo $(lightning-cli splice_init $CHANNEL_ID 100000 $INITIALPSBT) | jq -r \".psbt\")",
    "```",
    "4: Update the PSBT with the splice_update command.",
    "",
    "```shell",
    "PSBT_SPLICE_UPDATE=$(echo $(lightning-cli splice_update $CHANNEL_ID $PSBT_SPLICE_INIT) | jq -r \".psbt\")",
    "```",
    "5: Sign the updated PSBT.",
    "",
    "```shell",
    "SIGNPSBT=$(echo $(lightning-cli signpsbt -k psbt=\"$PSBT_SPLICE_UPDATE\") | jq -r \".signed_psbt\")",
    "```",
    "6: Finally, call splice_signed with channel id and signed PSBT parameters.",
    "",
    "```shell",
    "lightning-cli splice_signed $CHANNEL_ID $SIGNPSBT",
    "```"
  ],
  "author": [
    "Dusty <<@dusty_daemon>> is mainly responsible."
  ],
  "see_also": [
    "lightning-splice_signed(7)",
    "lightning-splice_update(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:splice_init#1",
        "method": "splice_init",
        "params": {
          "channel_id": "5677721c35a424a23d6dcc7c909036e505ae68650e09d59733b4b7e73003a4dc",
          "relative_amount": 100000,
          "initialpsbt": "cHNidP8BAF4CAAAAAVZ3chw1pCSiPW3MfJCQNuUFrmhlDgnVlzO0t+cwA6TcAQAAAAD9////AU58DQAAAAAAIlEgeDY1X9yKgtxMsAp3LFVUFR0GOEpN1l6NP2isCFZrhL5sAAAAAAEA9gIAAAAAAQGLpTM0gWEqICjgcZNyoPhzdB5fNZBrEFbsNpsKHrTd9wEAAAAA/f///wJAQg8AAAAAACIAIFuM07kUz2fN2Ppic8kwNT3TZHZzT72WIQLC31O5CIDNAS8PAAAAAAAiUSBj/+5Op9UebK35CG4oaiUnkiqqJbjFOuvzL6MqCmJ/WgJHMEQCIBZa5i8jVPdfV4pbIzSebMb5RN+l5lJkQKAw9+ivAWfnAiBNhehz79143DbFOoTjmPYVErlY0FLlVqojX9wat0aKXgEhA9dFRFyTYmZfIuDZbp52byc/MmDeo5yKdr+gXdJoTdzPGAAAAAEBKwEvDwAAAAAAIlEgY//uTqfVHmyt+QhuKGolJ5IqqiW4xTrr8y+jKgpif1oAAA=="
        }
      },
      "response": {
        "psbt": "cHNidP8BAgQCAAAAAQMEbAAAAAEEAQIBBQECAQYBAwH7BAIAAAAAAQD2AgAAAAABAYulMzSBYSogKOBxk3Kg+HN0Hl81kGsQVuw2mwoetN33AQAAAAD9////AkBCDwAAAAAAIgAgW4zTuRTPZ83Y+mJzyTA1PdNkdnNPvZYhAsLfU7kIgM0BLw8AAAAAACJRIGP/7k6n1R5srfkIbihqJSeSKqoluMU66/MvoyoKYn9aAkcwRAIgFlrmLyNU919XilsjNJ5sxvlE36XmUmRAoDD36K8BZ+cCIE2F6HPv3XjcNsU6hOOY9hUSuVjQUuVWqiNf3Bq3RopeASED10VEXJNiZl8i4NlunnZvJz8yYN6jnIp2v6Bd0mhN3M8YAAAAAQErQEIPAAAAAAAiACBbjNO5FM9nzdj6YnPJMDU902R2c0+9liECwt9TuQiAzQEFR1IhAjJCZt6EA7OrFXoJ8feE1YevYYMcmYwVG8whu3TCsjFLIQLjvTgAmGbJ2o7EqpnMTqnGwN1G3xXGHvDOHycSkXFOV1KuAQ4gVndyHDWkJKI9bcx8kJA25QWuaGUOCdWXM7S35zADpNwBDwQAAAAAARAEAAAAAAz8CWxpZ2h0bmluZwEIK/Jiqp0i3SYAAQD2AgAAAAABAYulMzSBYSogKOBxk3Kg+HN0Hl81kGsQVuw2mwoetN33AQAAAAD9////AkBCDwAAAAAAIgAgW4zTuRTPZ83Y+mJzyTA1PdNkdnNPvZYhAsLfU7kIgM0BLw8AAAAAACJRIGP/7k6n1R5srfkIbihqJSeSKqoluMU66/MvoyoKYn9aAkcwRAIgFlrmLyNU919XilsjNJ5sxvlE36XmUmRAoDD36K8BZ+cCIE2F6HPv3XjcNsU6hOOY9hUSuVjQUuVWqiNf3Bq3RopeASED10VEXJNiZl8i4NlunnZvJz8yYN6jnIp2v6Bd0mhN3M8YAAAAAQErAS8PAAAAAAAiUSBj/+5Op9UebK35CG4oaiUnkiqqJbjFOuvzL6MqCmJ/WgEOIFZ3chw1pCSiPW3MfJCQNuUFrmhlDgnVlzO0t+cwA6TcAQ8EAQAAAAEQBP3///8M/AlsaWdodG5pbmcBCDmPhBY5ChQUAAEDCE58DQAAAAAAAQQiUSB4NjVf3IqC3EywCncsVVQVHQY4Sk3WXo0/aKwIVmuEvgz8CWxpZ2h0bmluZwEIxt4P7eqf3+QAAQMIAAAAAAAAAAABBCIAIFuM07kUz2fN2Ppic8kwNT3TZHZzT72WIQLC31O5CIDNDPwJbGlnaHRuaW5nAQji6kH6aOXoAgA="
      }
    },
    {
      "request": {
        "id": "example:splice_init#2",
        "method": "splice_init",
        "params": {
          "channel_id": "a40bb442dab0231b51d8f842d95aad548aa35e1d13c4cfcf2997344f805453a1",
          "relative_amount": -105000,
          "initialpsbt": "cHNidP8BAgQCAAAAAQMEbAAAAAEEAQABBQEBAQYBAwH7BAIAAAAAAQMIoIYBAAAAAAABBCJRIHg2NV/cioLcTLAKdyxVVBUdBjhKTdZejT9orAhWa4S+AA=="
        }
      },
      "response": {
        "psbt": "cHNidP8BAgQCAAAAAQMEbAAAAAEEAQEBBQECAQYBAwH7BAIAAAAAAQD2AgAAAAABARzi7RBt64yrfqRL2p+KiUw8cYtiKICRFHmp/4eCSemSAQAAAAD9////AkBCDwAAAAAAIgAgW4zTuRTPZ83Y+mJzyTA1PdNkdnNPvZYhAsLfU7kIgM0BLw8AAAAAACJRIGP/7k6n1R5srfkIbihqJSeSKqoluMU66/MvoyoKYn9aAkcwRAIgTCjR9L+TfzP7pLJVVto5egTRbRNj/RaBhyrA3UW0aEcCIAJO5FZjXvdpRcGR949C4DnfHs3soklTjn/1upkia+TgASED10VEXJNiZl8i4NlunnZvJz8yYN6jnIp2v6Bd0mhN3M9mAAAAAQErQEIPAAAAAAAiACBbjNO5FM9nzdj6YnPJMDU902R2c0+9liECwt9TuQiAzQEFR1IhAjJCZt6EA7OrFXoJ8feE1YevYYMcmYwVG8whu3TCsjFLIQLjvTgAmGbJ2o7EqpnMTqnGwN1G3xXGHvDOHycSkXFOV1KuAQ4gpAu0QtqwIxtR2PhC2VqtVIqjXh0TxM/PKZc0T4BUU6EBDwQAAAAAARAEAAAAAAz8CWxpZ2h0bmluZwEIn2Ac8fyFEJwAAQMIAAAAAAAAAAABBCIAIFuM07kUz2fN2Ppic8kwNT3TZHZzT72WIQLC31O5CIDNDPwJbGlnaHRuaW5nAQgu7JK9IpBWOAABAwighgEAAAAAAAEEIlEgeDY1X9yKgtxMsAp3LFVUFR0GOEpN1l6NP2isCFZrhL4M/AlsaWdodG5pbmcBCOZ1GpRwbKfuAA=="
      }
    }
  ]
}