ExportChannelBackup

ExportChannelBackup attempts to return an encrypted static channel backup for the target channel identified by it channel point. The backup is encrypted with a key generated from the aezeed seed of the user. The returned backup can either be restored using the RestoreChannelBackup method once lnd is running, or via the InitWallet and UnlockWallet methods from the WalletUnlocker service.

Source: lightning.proto

gRPC

rpc ExportChannelBackup (ExportChannelBackupRequest) returns (ChannelBackup);

REST

HTTP Method	Path
GET	/v1/channels/backup/{chan_point.funding_txid_str}/{chan_point.output_index}

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 = {
  chan_point: <ChannelPoint>,
};
client.exportChannelBackup(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "chan_point": <ChannelPoint>,
//    "chan_backup": <bytes>,
//  }

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.ExportChannelBackupRequest(
  chan_point=<ChannelPoint>,
)
response = stub.ExportChannelBackup(request)
print(response)
# {
#    "chan_point": <ChannelPoint>,
#    "chan_backup": <bytes>,
# }

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 options = {
  url: `https://${REST_HOST}/v1/channels/backup/{chan_point.funding_txid_str}/{chan_point.output_index}`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "chan_point": <object>, // <ChannelPoint> 
//    "chan_backup": <string>, // <bytes> 
//  }

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/backup/{chan_point.funding_txid_str}/{chan_point.output_index}'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "chan_point": <ChannelPoint>,
#    "chan_backup": <bytes>,
# }

Shell

$ lncli exportchanbackup --help

NAME:
   lncli exportchanbackup - Obtain a static channel back up for a selected channels, or all known channels.

USAGE:
   lncli exportchanbackup [command options] [chan_point] [--all] [--output_file]

CATEGORY:
   Channels

DESCRIPTION:
   
  This command allows a user to export a Static Channel Backup (SCB) for
  a selected channel. SCB's are encrypted backups of a channel's initial
  state that are encrypted with a key derived from the seed of a user. In
  the case of partial or complete data loss, the SCB will allow the user
  to reclaim settled funds in the channel at its final state. The
  exported channel backups can be restored at a later time using the
  restorechanbackup command.

  This command will return one of two types of channel backups depending
  on the set of passed arguments:

     * If a target channel point is specified, then a single channel
       backup containing only the information for that channel will be
       returned.

     * If the --all flag is passed, then a multi-channel backup will be
       returned. A multi backup is a single encrypted blob (displayed in
       hex encoding) that contains several channels in a single cipher
       text.

  Both of the backup types can be restored using the restorechanbackup
  command.
  

OPTIONS:
   --chan_point value   the target channel to obtain an SCB for
   --all                if specified, then a multi backup of all active channels will be returned
   --output_file value  if specified, then rather than printing a JSON output
                            of the static channel backup, a serialized version of
                            the backup (either Single or Multi) will be written to
                            the target file, this is the same format used by lnd in
                            its channel.backup file
   

Messages

lnrpc.ExportChannelBackupRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
chan_point The target channel point to obtain a back up for. Nested REST Parameters chan_point.funding_txid_str: string in path chan_point.output_index: integer in path chan_point.funding_txid_bytes: string in query	ChannelPoint	object	mixed

lnrpc.ChannelBackup

Source: lightning.proto

Field	gRPC Type	REST Type
chan_point Identifies the channel that this backup belongs to.	ChannelPoint	object
chan_backup Is an encrypted single-chan backup. this can be passed to RestoreChannelBackups, or the WalletUnlocker Init and Unlock methods in order to trigger the recovery protocol. When using REST, this field must be encoded as base64.	bytes	string

Nested Messages

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