FundingStateStep

FundingStateStep is an advanced funding related call that allows the caller to either execute some preparatory steps for a funding workflow, or manually progress a funding workflow. The primary way a funding flow is identified is via its pending channel ID. As an example, this method can be used to specify that we're expecting a funding flow for a particular pending channel ID, for which we need to use specific parameters. Alternatively, this can be used to interactively drive PSBT signing for funding for partially complete funding transactions.

Source: lightning.proto

gRPC

rpc FundingStateStep (FundingTransitionMsg) returns (FundingStateStepResp);

REST

HTTP Method	Path
POST	/v1/funding/step

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('lightning.proto', loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new lnrpc.Lightning(GRPC_HOST, creds);
let request = {
  shim_register: <FundingShim>,
  shim_cancel: <FundingShimCancel>,
  psbt_verify: <FundingPsbtVerify>,
  psbt_finalize: <FundingPsbtFinalize>,
};
client.fundingStateStep(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lightning.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lightning_pb2 as lnrpc, lightning_pb2_grpc as lightningstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = lightningstub.LightningStub(channel)
request = lnrpc.FundingTransitionMsg(
  shim_register=<FundingShim>,
  shim_cancel=<FundingShimCancel>,
  psbt_verify=<FundingPsbtVerify>,
  psbt_finalize=<FundingPsbtFinalize>,
)
response = stub.FundingStateStep(request)
print(response)
# {
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let requestBody = {
  shim_register: <object>, // <FundingShim> 
  shim_cancel: <object>, // <FundingShimCancel> 
  psbt_verify: <object>, // <FundingPsbtVerify> 
  psbt_finalize: <object>, // <FundingPsbtFinalize> 
};
let options = {
  url: `https://${REST_HOST}/v1/funding/step`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/funding/step'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'shim_register': <FundingShim>,
  'shim_cancel': <FundingShimCancel>,
  'psbt_verify': <FundingPsbtVerify>,
  'psbt_finalize': <FundingPsbtFinalize>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.FundingTransitionMsg

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
shim_register The funding shim to register. This should be used before any channel funding has began by the remote party, as it is intended as a preparatory step for the full channel funding.	FundingShim	object	body
shim_cancel Used to cancel an existing registered funding shim.	FundingShimCancel	object	body
psbt_verify Used to continue a funding flow that was initiated to be executed through a PSBT. This step verifies that the PSBT contains the correct outputs to fund the channel.	FundingPsbtVerify	object	body
psbt_finalize Used to continue a funding flow that was initiated to be executed through a PSBT. This step finalizes the funded and signed PSBT, finishes negotiation with the peer and finally publishes the resulting funding transaction.	FundingPsbtFinalize	object	body

lnrpc.FundingStateStepResp

Source: lightning.proto

note

This response has no parameters.

Nested Messages

lnrpc.FundingShim

Field	gRPC Type	REST Type
chan_point_shim A channel shim where the channel point was fully constructed outside of lnd's wallet and the transaction might already be published.	ChanPointShim	object
psbt_shim A channel shim that uses a PSBT to fund and sign the channel funding transaction.	PsbtShim	object

lnrpc.ChanPointShim

Field	gRPC Type	REST Type
amt The size of the pre-crafted output to be used as the channel point for this channel funding.	int64	string
chan_point The target channel point to refrence in created commitment transactions.	ChannelPoint	object
local_key Our local key to use when creating the multi-sig output.	KeyDescriptor	object
remote_key The key of the remote party to use when creating the multi-sig output.	bytes	string
pending_chan_id If non-zero, then this will be used as the pending channel ID on the wire protocol to initate the funding request. This is an optional field, and should only be set if the responder is already expecting a specific pending channel ID.	bytes	string
thaw_height This uint32 indicates if this channel is to be considered 'frozen'. A frozen channel does not allow a cooperative channel close by the initiator. The thaw_height is the height that this restriction stops applying to the channel. The height can be interpreted in two ways: as a relative height if the value is less than 500,000, or as an absolute height otherwise.	uint32	integer

lnrpc.ChannelPoint

Field	gRPC Type	REST Type
funding_txid_bytes Txid of the funding transaction. When using REST, this field must be encoded as base64.	bytes	string
funding_txid_str Hex-encoded string representing the byte-reversed hash of the funding transaction.	string	string
output_index The index of the output of the funding transaction	uint32	integer

lnrpc.KeyDescriptor

Field	gRPC Type	REST Type
raw_key_bytes The raw bytes of the key being identified.	bytes	string
key_loc The key locator that identifies which key to use for signing.	KeyLocator	object

lnrpc.KeyLocator

Field	gRPC Type	REST Type
key_family The family of key being identified.	int32	integer
key_index The precise index of the key being identified.	int32	integer

lnrpc.PsbtShim

Field	gRPC Type	REST Type
pending_chan_id A unique identifier of 32 random bytes that will be used as the pending channel ID to identify the PSBT state machine when interacting with it and on the wire protocol to initiate the funding request.	bytes	string
base_psbt An optional base PSBT the new channel output will be added to. If this is non-empty, it must be a binary serialized PSBT.	bytes	string
no_publish If a channel should be part of a batch (multiple channel openings in one transaction), it can be dangerous if the whole batch transaction is published too early before all channel opening negotiations are completed. This flag prevents this particular channel from broadcasting the transaction after the negotiation with the remote peer. In a batch of channel openings this flag should be set to true for every channel but the very last.	bool	boolean

lnrpc.FundingShimCancel

Field	gRPC Type	REST Type
pending_chan_id The pending channel ID of the channel to cancel the funding shim for.	bytes	string

lnrpc.FundingPsbtVerify

Field	gRPC Type	REST Type
funded_psbt The funded but not yet signed PSBT that sends the exact channel capacity amount to the PK script returned in the open channel message in a previous step.	bytes	string
pending_chan_id The pending channel ID of the channel to get the PSBT for.	bytes	string
skip_finalize Can only be used if the nopublish flag was set to true in the OpenChannel call meaning that the caller is solely responsible for publishing the final funding transaction. If skip_finalize is set to true then lnd will not wait for a FundingPsbtFinalize state step and instead assumes that a transaction with the same TXID as the passed in PSBT will eventually confirm. IT IS ABSOLUTELY IMPERATIVE that the TXID of the transaction that is eventually published does have the _same TXID as the verified PSBT. That means no inputs or outputs can change, only signatures can be added. If the TXID changes between this call and the publish step then the channel will never be created and the funds will be in limbo.	bool	boolean

lnrpc.FundingPsbtFinalize

Field	gRPC Type	REST Type
signed_psbt The funded PSBT that contains all witness data to send the exact channel capacity amount to the PK script returned in the open channel message in a previous step. Cannot be set at the same time as final_raw_tx.	bytes	string
pending_chan_id The pending channel ID of the channel to get the PSBT for.	bytes	string
final_raw_tx As an alternative to the signed PSBT with all witness data, the final raw wire format transaction can also be specified directly. Cannot be set at the same time as signed_psbt.	bytes	string