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

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "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"
    ],
    "additionalProperties": false,
    "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"
    ],
    "additionalProperties": false,
    "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": "channelid0780000780000780000780000780000780000780000780000780000",
          "relative_amount": 100000,
          "initialpsbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000713000"
        }
      },
      "response": {
        "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000"
      }
    },
    {
      "request": {
        "id": "example:splice_init#2",
        "method": "splice_init",
        "params": [
          "channelid0780000780000780000780000780000780000780000780000780000",
          -105000,
          "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000714000"
        ]
      },
      "response": {
        "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000"
      }
    }
  ]
}