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

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "added": "v23.08",
  "rpc": "splice_update",
  "title": "Command to initiate a channel to a peer",
  "warning": "experimental-splicing only",
  "description": [
    "`splice_update` is a low level RPC command which updates the active channel splice associated with `channel_id`.",
    "",
    "`splice_update` must be called repeatidly until the result `commitments_secured` is `true`. Each time `splice_update` is called, it will return a new PSBT that may have changes. In the simplest case, you take the returned `psbt` and pass it back into `splice_update` for the incoming `psbt` field.",
    "",
    "For more complex use cases, you may modify the `psbt` both before calling `splice_update` and inbetween subsequent calls until `commitments_secured` is `true`. After which point you can no long make modifications to the PSBT (beyond signing, which comes later with `splice_signed`).",
    "",
    "Each `splice_update` result may include changes to the PSBT specified by your channel peer. You can review these changes between calls to `splice_update` to perform additional validation or strategy adjustment.",
    "",
    "Typically, `splice_update` will return `commitments_secured` true after one call but you should assume it will need multiple calls."
  ],
  "request": {
    "required": [
      "channel_id",
      "psbt"
    ],
    "additionalProperties": false,
    "properties": {
      "channel_id": {
        "type": "hash",
        "description": [
          "The channel id of the channel to be spliced."
        ]
      },
      "psbt": {
        "type": "string",
        "description": [
          "The base 64 encoded PSBT returned from `splice_init` with any changes added by the user."
        ]
      }
    }
  },
  "response": {
    "required": [
      "psbt",
      "commitments_secured",
      "signatures_secured"
    ],
    "additionalProperties": false,
    "properties": {
      "psbt": {
        "type": "string",
        "description": [
          "The (incomplete) PSBT of the splice transaction."
        ]
      },
      "commitments_secured": {
        "type": "boolean",
        "description": [
          "Whether or not the commitments were secured."
        ]
      },
      "signatures_secured": {
        "added": "v24.11",
        "type": "boolean",
        "description": [
          "whether or not the peer sent us their signatures for this splice"
        ]
      }
    }
  },
  "usage": [
    "Here is an example way to call `splice_update`",
    "",
    "```shell",
    "RESULT={\"commitments_secured\":false}",
    "while [[ $(echo $RESULT | jq -r \".commitments_secured\") == \"false\" ]]",
    "do",
    "  RESULT=$(lightning-cli splice_update $CHANNEL_ID $PSBT)",
    "  PSBT=$(echo $RESULT | jq -r \".psbt\")",
    "  echo $RESULT",
    "done",
    "```",
    "",
    "Before each call to `splice_update` you have the opportunity to make additional changes.",
    "",
    "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 PSBTs with the splice_update command.",
    "",
    "```shell",
    "RESULT={\"commitments_secured\":false}",
    "while [[ $(echo $RESULT | jq -r \".commitments_secured\") == \"false\" ]]",
    "do",
    "  PSBT_SPLICE_UPDATE=$(echo $(lightning-cli splice_update $CHANNEL_ID $PSBT_SPLICE_INIT) | jq -r \".psbt\")",
    "  echo $PSBT_SPLICE_UPDATE",
    "done",
    "```",
    "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_init(7)",
    "lightning-splice_signed(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:splice_update#1",
        "method": "splice_update",
        "params": {
          "channel_id": "channelid0780000780000780000780000780000780000780000780000780000",
          "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000711000"
        }
      },
      "response": {
        "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200715200",
        "commitments_secured": true,
        "signatures_secured": true
      }
    },
    {
      "request": {
        "id": "example:splice_update#2",
        "method": "splice_update",
        "params": [
          "channelid0780000780000780000780000780000780000780000780000780000",
          "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000"
        ]
      },
      "response": {
        "psbt": "cHNidP8BAgQCAAAAAQMEbwAAAAEEAQpsbt712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000712000",
        "commitments_secured": true,
        "signatures_secured": true
      }
    }
  ]
}