OpenChannelSync

OpenChannelSync is a synchronous version of the OpenChannel RPC call. This call is meant to be consumed by clients to the REST proxy. As with all other sync calls, all byte slices are intended to be populated as hex encoded strings.

Source: lightning.proto

gRPC

rpc OpenChannelSync (OpenChannelRequest) returns (ChannelPoint);

REST

HTTP Method	Path
POST	/v1/channels

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 = {
  sat_per_vbyte: <uint64>,
  node_pubkey: <bytes>,
  node_pubkey_string: <string>,
  local_funding_amount: <int64>,
  push_sat: <int64>,
  target_conf: <int32>,
  sat_per_byte: <int64>,
  private: <bool>,
  min_htlc_msat: <int64>,
  remote_csv_delay: <uint32>,
  min_confs: <int32>,
  spend_unconfirmed: <bool>,
  close_address: <string>,
  funding_shim: <FundingShim>,
  remote_max_value_in_flight_msat: <uint64>,
  remote_max_htlcs: <uint32>,
  max_local_csv: <uint32>,
  commitment_type: <CommitmentType>,
  zero_conf: <bool>,
  scid_alias: <bool>,
  base_fee: <uint64>,
  fee_rate: <uint64>,
  use_base_fee: <bool>,
  use_fee_rate: <bool>,
  remote_chan_reserve_sat: <uint64>,
};
client.openChannelSync(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "funding_txid_bytes": <bytes>,
//    "funding_txid_str": <string>,
//    "output_index": <uint32>,
//  }

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.OpenChannelRequest(
  sat_per_vbyte=<uint64>,
  node_pubkey=<bytes>,
  node_pubkey_string=<string>,
  local_funding_amount=<int64>,
  push_sat=<int64>,
  target_conf=<int32>,
  sat_per_byte=<int64>,
  private=<bool>,
  min_htlc_msat=<int64>,
  remote_csv_delay=<uint32>,
  min_confs=<int32>,
  spend_unconfirmed=<bool>,
  close_address=<string>,
  funding_shim=<FundingShim>,
  remote_max_value_in_flight_msat=<uint64>,
  remote_max_htlcs=<uint32>,
  max_local_csv=<uint32>,
  commitment_type=<CommitmentType>,
  zero_conf=<bool>,
  scid_alias=<bool>,
  base_fee=<uint64>,
  fee_rate=<uint64>,
  use_base_fee=<bool>,
  use_fee_rate=<bool>,
  remote_chan_reserve_sat=<uint64>,
)
response = stub.OpenChannelSync(request)
print(response)
# {
#    "funding_txid_bytes": <bytes>,
#    "funding_txid_str": <string>,
#    "output_index": <uint32>,
# }

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 = {
  sat_per_vbyte: <string>, // <uint64> 
  node_pubkey: <string>, // <bytes> (base64 encoded)
  node_pubkey_string: <string>, // <string> 
  local_funding_amount: <string>, // <int64> 
  push_sat: <string>, // <int64> 
  target_conf: <integer>, // <int32> 
  sat_per_byte: <string>, // <int64> 
  private: <boolean>, // <bool> 
  min_htlc_msat: <string>, // <int64> 
  remote_csv_delay: <integer>, // <uint32> 
  min_confs: <integer>, // <int32> 
  spend_unconfirmed: <boolean>, // <bool> 
  close_address: <string>, // <string> 
  funding_shim: <object>, // <FundingShim> 
  remote_max_value_in_flight_msat: <string>, // <uint64> 
  remote_max_htlcs: <integer>, // <uint32> 
  max_local_csv: <integer>, // <uint32> 
  commitment_type: <string>, // <CommitmentType> 
  zero_conf: <boolean>, // <bool> 
  scid_alias: <boolean>, // <bool> 
  base_fee: <string>, // <uint64> 
  fee_rate: <string>, // <uint64> 
  use_base_fee: <boolean>, // <bool> 
  use_fee_rate: <boolean>, // <bool> 
  remote_chan_reserve_sat: <string>, // <uint64> 
};
let options = {
  url: `https://${REST_HOST}/v1/channels`,
  // 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:
//  {
//    "funding_txid_bytes": <string>, // <bytes> 
//    "funding_txid_str": <string>, // <string> 
//    "output_index": <integer>, // <uint32> 
//  }

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/channels'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'sat_per_vbyte': <uint64>,
  'node_pubkey': base64.b64encode(<bytes>),
  'node_pubkey_string': <string>,
  'local_funding_amount': <int64>,
  'push_sat': <int64>,
  'target_conf': <int32>,
  'sat_per_byte': <int64>,
  'private': <bool>,
  'min_htlc_msat': <int64>,
  'remote_csv_delay': <uint32>,
  'min_confs': <int32>,
  'spend_unconfirmed': <bool>,
  'close_address': <string>,
  'funding_shim': <FundingShim>,
  'remote_max_value_in_flight_msat': <uint64>,
  'remote_max_htlcs': <uint32>,
  'max_local_csv': <uint32>,
  'commitment_type': <CommitmentType>,
  'zero_conf': <bool>,
  'scid_alias': <bool>,
  'base_fee': <uint64>,
  'fee_rate': <uint64>,
  'use_base_fee': <bool>,
  'use_fee_rate': <bool>,
  'remote_chan_reserve_sat': <uint64>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "funding_txid_bytes": <bytes>,
#    "funding_txid_str": <string>,
#    "output_index": <uint32>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.OpenChannelRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
sat_per_vbyte A manual fee rate set in sat/vbyte that should be used when crafting the funding transaction.	uint64	string	body
node_pubkey The pubkey of the node to open a channel with. When using REST, this field must be encoded as base64.	bytes	string	body
node_pubkey_string The hex encoded pubkey of the node to open a channel with. Deprecated now that the REST gateway supports base64 encoding of bytes fields.	string	string	body
local_funding_amount The number of satoshis the wallet should commit to the channel	int64	string	body
push_sat The number of satoshis to push to the remote side as part of the initial commitment state	int64	string	body
target_conf The target number of blocks that the funding transaction should be confirmed by.	int32	integer	body
sat_per_byte Deprecated, use sat_per_vbyte. A manual fee rate set in sat/vbyte that should be used when crafting the funding transaction.	int64	string	body
private Whether this channel should be private, not announced to the greater network.	bool	boolean	body
min_htlc_msat The minimum value in millisatoshi we will require for incoming HTLCs on the channel.	int64	string	body
remote_csv_delay The delay we require on the remote's commitment transaction. If this is not set, it will be scaled automatically with the channel size.	uint32	integer	body
min_confs The minimum number of confirmations each one of your outputs used for the funding transaction must satisfy.	int32	integer	body
spend_unconfirmed Whether unconfirmed outputs should be used as inputs for the funding transaction.	bool	boolean	body
close_address Close address is an optional address which specifies the address to which funds should be paid out to upon cooperative close. This field may only be set if the peer supports the option upfront feature bit (call listpeers to check). The remote peer will only accept cooperative closes to this address if it is set. Note: If this value is set on channel creation, you will not be able to cooperatively close out to a different address.	string	string	body
funding_shim Funding shims are an optional argument that allow the caller to intercept certain funding functionality. For example, a shim can be provided to use a particular key for the commitment key (ideally cold) rather than use one that is generated by the wallet as normal, or signal that signing will be carried out in an interactive manner (PSBT based).	FundingShim	object	body
remote_max_value_in_flight_msat The maximum amount of coins in millisatoshi that can be pending within the channel. It only applies to the remote party.	uint64	string	body
remote_max_htlcs The maximum number of concurrent HTLCs we will allow the remote party to add to the commitment transaction.	uint32	integer	body
max_local_csv Max local csv is the maximum csv delay we will allow for our own commitment transaction.	uint32	integer	body
commitment_type The explicit commitment type to use. Note this field will only be used if the remote peer supports explicit channel negotiation.	CommitmentType	string	body
zero_conf If this is true, then a zero-conf channel open will be attempted.	bool	boolean	body
scid_alias If this is true, then an option-scid-alias channel-type open will be attempted.	bool	boolean	body
base_fee The base fee charged regardless of the number of milli-satoshis sent.	uint64	string	body
fee_rate The fee rate in ppm (parts per million) that will be charged in proportion of the value of each forwarded HTLC.	uint64	string	body
use_base_fee If use_base_fee is true the open channel announcement will update the channel base fee with the value specified in base_fee. In the case of a base_fee of 0 use_base_fee is needed downstream to distinguish whether to use the default base fee value specified in the config or 0.	bool	boolean	body
use_fee_rate If use_fee_rate is true the open channel announcement will update the channel fee rate with the value specified in fee_rate. In the case of a fee_rate of 0 use_fee_rate is needed downstream to distinguish whether to use the default fee rate value specified in the config or 0.	bool	boolean	body
remote_chan_reserve_sat The number of satoshis we require the remote peer to reserve. This value, if specified, must be above the dust limit and below 20% of the channel capacity.	uint64	string	body

lnrpc.ChannelPoint

Source: lightning.proto

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

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

Enums

lnrpc.CommitmentType

Name	Number
UNKNOWN_COMMITMENT_TYPE Returned when the commitment type isn't known or unavailable.	0
LEGACY A channel using the legacy commitment format having tweaked to_remote keys.	1
STATIC_REMOTE_KEY A channel that uses the modern commitment format where the key in the output of the remote party does not change each state. This makes back up and recovery easier as when the channel is closed, the funds go directly to that key.	2
ANCHORS A channel that uses a commitment format that has anchor outputs on the commitments, allowing fee bumping after a force close transaction has been broadcast.	3
SCRIPT_ENFORCED_LEASE A channel that uses a commitment type that builds upon the anchors commitment format, but in addition requires a CLTV clause to spend outputs paying to the channel initiator. This is intended for use on leased channels to guarantee that the channel initiator has no incentives to close a leased channel before its maturity date.	4