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>,
};
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>,
)
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> 
};
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>,
}
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
   

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

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

lnrpc.PendingUpdate

Field	gRPC Type	REST Type
txid	bytes	string
output_index	uint32	integer

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