BatchOpenChannel

BatchOpenChannel attempts to open multiple single-funded channels in a single transaction in an atomic way. This means either all channel open requests succeed at once or all attempts are aborted if any of them fail. This is the safer variant of using PSBTs to manually fund a batch of channels through the OpenChannel RPC.

Source: lightning.proto

gRPC

rpc BatchOpenChannel (BatchOpenChannelRequest) returns (BatchOpenChannelResponse);

REST

HTTP Method	Path
POST	/v1/channels/batch

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 = {
  channels: <BatchOpenChannel>,
  target_conf: <int32>,
  sat_per_vbyte: <int64>,
  min_confs: <int32>,
  spend_unconfirmed: <bool>,
  label: <string>,
  coin_selection_strategy: <CoinSelectionStrategy>,
};
client.batchOpenChannel(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "pending_channels": <PendingUpdate>,
//  }

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.BatchOpenChannelRequest(
  channels=<BatchOpenChannel>,
  target_conf=<int32>,
  sat_per_vbyte=<int64>,
  min_confs=<int32>,
  spend_unconfirmed=<bool>,
  label=<string>,
  coin_selection_strategy=<CoinSelectionStrategy>,
)
response = stub.BatchOpenChannel(request)
print(response)
# {
#    "pending_channels": <PendingUpdate>,
# }

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 = {
  channels: <array>, // <BatchOpenChannel> 
  target_conf: <integer>, // <int32> 
  sat_per_vbyte: <string>, // <int64> 
  min_confs: <integer>, // <int32> 
  spend_unconfirmed: <boolean>, // <bool> 
  label: <string>, // <string> 
  coin_selection_strategy: <string>, // <CoinSelectionStrategy> 
};
let options = {
  url: `https://${REST_HOST}/v1/channels/batch`,
  // 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:
//  {
//    "pending_channels": <array>, // <PendingUpdate> 
//  }

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/batch'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'channels': <BatchOpenChannel>,
  'target_conf': <int32>,
  'sat_per_vbyte': <int64>,
  'min_confs': <int32>,
  'spend_unconfirmed': <bool>,
  'label': <string>,
  'coin_selection_strategy': <CoinSelectionStrategy>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "pending_channels": <PendingUpdate>,
# }

Shell

$ lncli batchopenchannel --help

NAME:
   lncli batchopenchannel - Open multiple channels to existing peers in a single transaction.

USAGE:
   lncli batchopenchannel [command options] channels-json

CATEGORY:
   Channels

DESCRIPTION:
   
  Attempt to open one or more new channels to an existing peer with the
  given node-keys.

  Example:
  lncli batchopenchannel --sat_per_vbyte=5 '[{
    "node_pubkey": "02abcdef...",
    "local_funding_amount": 500000,
    "private": true,
    "close_address": "bc1qxxx..."
  }, {
    "node_pubkey": "03fedcba...",
    "local_funding_amount": 200000,
    "remote_csv_delay": 288
  }]'

  All nodes listed must already be connected peers, otherwise funding will
  fail.

  The channel will be initialized with local_funding_amount satoshis 
  locally and push_sat satoshis for the remote node. Note that specifying 
  push_sat means you give that amount to the remote node as part of the 
  channel  opening. Once the channel is open, a channelPoint (txid:vout) of 
  the funding output is returned.

  If the remote peer supports the option upfront shutdown feature bit
  (query listpeers to see their supported feature bits), an address to
  enforce  payout of funds on cooperative close can optionally be provided.
  Note that if you set this value, you will not be able to cooperatively
  close out to another address.

  One can manually set the fee to be used for the funding transaction via
  either the --conf_target or --sat_per_vbyte arguments. This is optional.


OPTIONS:
   --conf_target value              (optional) the number of blocks that the transaction *should* confirm in, will be used for fee estimation (default: 0)
   --sat_per_vbyte value            (optional) a manual fee expressed in sat/vByte that should be used when crafting the transaction (default: 0)
   --min_confs value                (optional) the minimum number of confirmations each one of your outputs used for the funding transaction must satisfy (default: 1)
   --label value                    (optional) a label to attach to the batch transaction when storing it to the local wallet after publishing it
   --coin_selection_strategy value  (optional) the strategy to use for selecting coins. Possible values are 'largest', 'random', or 'global-config'. If either 'largest' or 'random' is specified, it will override the globally configured strategy in lnd.conf (default: "global-config")
   

Messages

lnrpc.BatchOpenChannelRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
channels The list of channels to open.	BatchOpenChannel[]	array	body
target_conf The target number of blocks that the funding transaction should be confirmed by.	int32	integer	body
sat_per_vbyte A manual fee rate set in sat/vByte that should be used when crafting the funding transaction.	int64	string	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
label An optional label for the batch transaction, limited to 500 characters.	string	string	body
coin_selection_strategy The strategy to use for selecting coins during batch opening channels.	CoinSelectionStrategy	string	body

lnrpc.BatchOpenChannelResponse

Source: lightning.proto

Field	gRPC Type	REST Type
pending_channels	PendingUpdate[]	array

Nested Messages

lnrpc.BatchOpenChannel

Field	gRPC Type	REST Type
node_pubkey The pubkey of the node to open a channel with. When using REST, this field must be encoded as base64.	bytes	string
local_funding_amount The number of satoshis the wallet should commit to the channel.	int64	string
push_sat The number of satoshis to push to the remote side as part of the initial commitment state.	int64	string
private Whether this channel should be private, not announced to the greater network.	bool	boolean
min_htlc_msat The minimum value in millisatoshi we will require for incoming HTLCs on the channel.	int64	string
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
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
pending_chan_id An optional, unique identifier of 32 random bytes that will be used as the pending channel ID to identify the channel while it is in the pre-pending state.	bytes	string
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
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
remote_max_htlcs The maximum number of concurrent HTLCs we will allow the remote party to add to the commitment transaction.	uint32	integer
max_local_csv Max local csv is the maximum csv delay we will allow for our own commitment transaction.	uint32	integer
zero_conf If this is true, then a zero-conf channel open will be attempted.	bool	boolean
scid_alias If this is true, then an option-scid-alias channel-type open will be attempted.	bool	boolean
base_fee The base fee charged regardless of the number of milli-satoshis sent.	uint64	string
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
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
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
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
memo An optional note-to-self to go along with the channel containing some useful information. This is only ever stored locally and in no way impacts the channel's operation.	string	string

lnrpc.PendingUpdate

Field	gRPC Type	REST Type
txid	bytes	string
output_index	uint32	integer

Enums

lnrpc.CoinSelectionStrategy

Name	Number
STRATEGY_USE_GLOBAL_CONFIG Use the coin selection strategy defined in the global configuration (lnd.conf).	0
STRATEGY_LARGEST Select the largest available coins first during coin selection.	1
STRATEGY_RANDOM Randomly select the available coins during coin selection.	2

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
SIMPLE_TAPROOT TODO(roasbeef): need script enforce mirror type for the above as well?	5