ChannelAcceptor

ChannelAcceptor dispatches a bi-directional streaming RPC in which OpenChannel requests are sent to the client and the client responds with a boolean that tells LND whether or not to accept the channel. This allows node operators to specify their own criteria for accepting inbound channels through a single persistent connection.

Source: lightning.proto

gRPC

info

This is a bidirectional-streaming RPC

rpc ChannelAcceptor (stream ChannelAcceptResponse) returns (stream ChannelAcceptRequest);

REST

HTTP Method	Path
POST	/v1/channels/acceptor

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 = {
  accept: <bool>,
  pending_chan_id: <bytes>,
  error: <string>,
  upfront_shutdown: <string>,
  csv_delay: <uint32>,
  reserve_sat: <uint64>,
  in_flight_max_msat: <uint64>,
  max_htlc_count: <uint32>,
  min_htlc_in: <uint64>,
  min_accept_depth: <uint32>,
  zero_conf: <bool>,
};
let call = client.channelAcceptor({});
call.on('data', function(response) {
  // A response was received from the server.
  console.log(response);
});
call.on('status', function(status) {
  // The current status of the stream.
});
call.on('end', function() {
  // The server has closed the stream.
});
call.write(request);
// Console output:
//  {
//    "node_pubkey": <bytes>,
//    "chain_hash": <bytes>,
//    "pending_chan_id": <bytes>,
//    "funding_amt": <uint64>,
//    "push_amt": <uint64>,
//    "dust_limit": <uint64>,
//    "max_value_in_flight": <uint64>,
//    "channel_reserve": <uint64>,
//    "min_htlc": <uint64>,
//    "fee_per_kw": <uint64>,
//    "csv_delay": <uint32>,
//    "max_accepted_htlcs": <uint32>,
//    "channel_flags": <uint32>,
//    "commitment_type": <CommitmentType>,
//    "wants_zero_conf": <bool>,
//    "wants_scid_alias": <bool>,
//  }

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)
# Define a generator that returns an Iterable of ChannelAcceptResponse objects.
def request_generator():
    # Initialization code here.
    while True:
        # Parameters here can be set as arguments to the generator.
        request = lnrpc.ChannelAcceptResponse(
            accept=<bool>,
            pending_chan_id=<bytes>,
            error=<string>,
            upfront_shutdown=<string>,
            csv_delay=<uint32>,
            reserve_sat=<uint64>,
            in_flight_max_msat=<uint64>,
            max_htlc_count=<uint32>,
            min_htlc_in=<uint64>,
            min_accept_depth=<uint32>,
            zero_conf=<bool>,
        )
        yield request
        # Do things between iterations here.
request_iterable = request_generator()
for response in stub.ChannelAcceptor(request_iterable):
  print(response)
# {
#    "node_pubkey": <bytes>,
#    "chain_hash": <bytes>,
#    "pending_chan_id": <bytes>,
#    "funding_amt": <uint64>,
#    "push_amt": <uint64>,
#    "dust_limit": <uint64>,
#    "max_value_in_flight": <uint64>,
#    "channel_reserve": <uint64>,
#    "min_htlc": <uint64>,
#    "fee_per_kw": <uint64>,
#    "csv_delay": <uint32>,
#    "max_accepted_htlcs": <uint32>,
#    "channel_flags": <uint32>,
#    "commitment_type": <CommitmentType>,
#    "wants_zero_conf": <bool>,
#    "wants_scid_alias": <bool>,
# }

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 = {
  accept: <boolean>, // <bool> 
  pending_chan_id: <string>, // <bytes> (base64 encoded)
  error: <string>, // <string> 
  upfront_shutdown: <string>, // <string> 
  csv_delay: <integer>, // <uint32> 
  reserve_sat: <string>, // <uint64> 
  in_flight_max_msat: <string>, // <uint64> 
  max_htlc_count: <integer>, // <uint32> 
  min_htlc_in: <string>, // <uint64> 
  min_accept_depth: <integer>, // <uint32> 
  zero_conf: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/channels/acceptor`,
  // 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:
//  {
//    "node_pubkey": <string>, // <bytes> 
//    "chain_hash": <string>, // <bytes> 
//    "pending_chan_id": <string>, // <bytes> 
//    "funding_amt": <string>, // <uint64> 
//    "push_amt": <string>, // <uint64> 
//    "dust_limit": <string>, // <uint64> 
//    "max_value_in_flight": <string>, // <uint64> 
//    "channel_reserve": <string>, // <uint64> 
//    "min_htlc": <string>, // <uint64> 
//    "fee_per_kw": <string>, // <uint64> 
//    "csv_delay": <integer>, // <uint32> 
//    "max_accepted_htlcs": <integer>, // <uint32> 
//    "channel_flags": <integer>, // <uint32> 
//    "commitment_type": <string>, // <CommitmentType> 
//    "wants_zero_conf": <boolean>, // <bool> 
//    "wants_scid_alias": <boolean>, // <bool> 
//  }



// --------------------------
// Example with websockets:
// --------------------------
const WebSocket = require('ws');
const fs = require('fs');

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

let ws = new WebSocket(`wss://${REST_HOST}/v1/channels/acceptor?method=POST`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
  accept: <bool>, // <bool> 
  pending_chan_id: <bytes>, // <bytes> (base64 encoded)
  error: <string>, // <string> 
  upfront_shutdown: <string>, // <string> 
  csv_delay: <uint32>, // <uint32> 
  reserve_sat: <uint64>, // <uint64> 
  in_flight_max_msat: <uint64>, // <uint64> 
  max_htlc_count: <uint32>, // <uint32> 
  min_htlc_in: <uint64>, // <uint64> 
  min_accept_depth: <uint32>, // <uint32> 
  zero_conf: <bool>, // <bool> 
};
ws.on('open', function() {
    ws.send(JSON.stringify(requestBody));
});
ws.on('error', function(err) {
    console.log('Error: ' + err);
});
ws.on('message', function(body) {
    console.log(body);
});
// Console output:
//  {
//    "node_pubkey": <string>, // <bytes>
//    "chain_hash": <string>, // <bytes>
//    "pending_chan_id": <string>, // <bytes>
//    "funding_amt": <string>, // <uint64>
//    "push_amt": <string>, // <uint64>
//    "dust_limit": <string>, // <uint64>
//    "max_value_in_flight": <string>, // <uint64>
//    "channel_reserve": <string>, // <uint64>
//    "min_htlc": <string>, // <uint64>
//    "fee_per_kw": <string>, // <uint64>
//    "csv_delay": <integer>, // <uint32>
//    "max_accepted_htlcs": <integer>, // <uint32>
//    "channel_flags": <integer>, // <uint32>
//    "commitment_type": <string>, // <CommitmentType>
//    "wants_zero_conf": <boolean>, // <bool>
//    "wants_scid_alias": <boolean>, // <bool>
//  }

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/acceptor'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'accept': <bool>,
  'pending_chan_id': base64.b64encode(<bytes>),
  'error': <string>,
  'upfront_shutdown': <string>,
  'csv_delay': <uint32>,
  'reserve_sat': <uint64>,
  'in_flight_max_msat': <uint64>,
  'max_htlc_count': <uint32>,
  'min_htlc_in': <uint64>,
  'min_accept_depth': <uint32>,
  'zero_conf': <bool>,
}
r = requests.post(url, headers=headers, stream=True, data=json.dumps(data), verify=TLS_PATH)
for raw_response in r.iter_lines():
  json_response = json.loads(raw_response)
  print(json_response)
# {
#    "node_pubkey": <bytes>,
#    "chain_hash": <bytes>,
#    "pending_chan_id": <bytes>,
#    "funding_amt": <uint64>,
#    "push_amt": <uint64>,
#    "dust_limit": <uint64>,
#    "max_value_in_flight": <uint64>,
#    "channel_reserve": <uint64>,
#    "min_htlc": <uint64>,
#    "fee_per_kw": <uint64>,
#    "csv_delay": <uint32>,
#    "max_accepted_htlcs": <uint32>,
#    "channel_flags": <uint32>,
#    "commitment_type": <CommitmentType>,
#    "wants_zero_conf": <bool>,
#    "wants_scid_alias": <bool>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.ChannelAcceptResponse

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
accept Whether or not the client accepts the channel.	bool	boolean	body
pending_chan_id The pending channel id to which this response applies.	bytes	string	body
error An optional error to send the initiating party to indicate why the channel was rejected. This field should not contain sensitive information, it will be sent to the initiating party. This field should only be set if accept is false, the channel will be rejected if an error is set with accept=true because the meaning of this response is ambiguous. Limited to 500 characters.	string	string	body
upfront_shutdown The upfront shutdown address to use if the initiating peer supports option upfront shutdown script (see ListPeers for the features supported). Note that the channel open will fail if this value is set for a peer that does not support this feature bit.	string	string	body
csv_delay The csv delay (in blocks) that we require for the remote party.	uint32	integer	body
reserve_sat The reserve amount in satoshis that we require the remote peer to adhere to. We require that the remote peer always have some reserve amount allocated to them so that there is always a disincentive to broadcast old state (if they hold 0 sats on their side of the channel, there is nothing to lose).	uint64	string	body
in_flight_max_msat The maximum amount of funds in millisatoshis that we allow the remote peer to have in outstanding htlcs.	uint64	string	body
max_htlc_count The maximum number of htlcs that the remote peer can offer us.	uint32	integer	body
min_htlc_in The minimum value in millisatoshis for incoming htlcs on the channel.	uint64	string	body
min_accept_depth The number of confirmations we require before we consider the channel open.	uint32	integer	body
zero_conf Whether the responder wants this to be a zero-conf channel. This will fail if either side does not have the scid-alias feature bit set. The minimum depth field must be zero if this is true.	bool	boolean	body

lnrpc.ChannelAcceptRequest

Source: lightning.proto

Field	gRPC Type	REST Type
node_pubkey The pubkey of the node that wishes to open an inbound channel.	bytes	string
chain_hash The hash of the genesis block that the proposed channel resides in.	bytes	string
pending_chan_id The pending channel id.	bytes	string
funding_amt The funding amount in satoshis that initiator wishes to use in the channel.	uint64	string
push_amt The push amount of the proposed channel in millisatoshis.	uint64	string
dust_limit The dust limit of the initiator's commitment tx.	uint64	string
max_value_in_flight The maximum amount of coins in millisatoshis that can be pending in this channel.	uint64	string
channel_reserve The minimum amount of satoshis the initiator requires us to have at all times.	uint64	string
min_htlc The smallest HTLC in millisatoshis that the initiator will accept.	uint64	string
fee_per_kw The initial fee rate that the initiator suggests for both commitment transactions.	uint64	string
csv_delay The number of blocks to use for the relative time lock in the pay-to-self output of both commitment transactions.	uint32	integer
max_accepted_htlcs The total number of incoming HTLC's that the initiator will accept.	uint32	integer
channel_flags A bit-field which the initiator uses to specify proposed channel behavior.	uint32	integer
commitment_type The commitment type the initiator wishes to use for the proposed channel.	CommitmentType	string
wants_zero_conf Whether the initiator wants to open a zero-conf channel via the channel type.	bool	boolean
wants_scid_alias Whether the initiator wants to use the scid-alias channel type. This is separate from the feature bit.	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