RestoreChannelBackups

RestoreChannelBackups accepts a set of singular channel backups, or a single encrypted multi-chan backup and attempts to recover any funds remaining within the channel. If we are able to unpack the backup, then the new channel will be shown under listchannels, as well as pending channels.

Source: lightning.proto

gRPC

rpc RestoreChannelBackups (RestoreChanBackupRequest) returns (RestoreBackupResponse);

REST

HTTP Method	Path
POST	/v1/channels/backup/restore

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_backups: <ChannelBackups>,
  multi_chan_backup: <bytes>,
};
client.restoreChannelBackups(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "num_restored": <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.RestoreChanBackupRequest(
  chan_backups=<ChannelBackups>,
  multi_chan_backup=<bytes>,
)
response = stub.RestoreChannelBackups(request)
print(response)
# {
#    "num_restored": <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 = {
  chan_backups: <object>, // <ChannelBackups> 
  multi_chan_backup: <string>, // <bytes> (base64 encoded)
};
let options = {
  url: `https://${REST_HOST}/v1/channels/backup/restore`,
  // 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:
//  {
//    "num_restored": <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/backup/restore'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'chan_backups': <ChannelBackups>,
  'multi_chan_backup': base64.b64encode(<bytes>),
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "num_restored": <uint32>,
# }

Shell

$ lncli restorechanbackup --help

NAME:
   lncli restorechanbackup - Restore an existing single or multi-channel static channel backup.

USAGE:
   lncli restorechanbackup [command options] [--single_backup] [--multi_backup] [--multi_file=

CATEGORY:
   Channels

DESCRIPTION:
   
  Allows a user to restore a Static Channel Backup (SCB) that was
  obtained either via the exportchanbackup command, or from lnd's
  automatically managed channel.backup file. This command should be used
  if a user is attempting to restore a channel due to data loss on a
  running node restored with the same seed as the node that created the
  channel. If successful, this command will allows the user to recover
  the settled funds stored in the recovered channels.

  The command will accept backups in one of four forms:

     * A single channel packed SCB, which can be obtained from
       exportchanbackup. This should be passed in hex encoded format.

     * A packed multi-channel SCB, which couples several individual
       static channel backups in single blob.

     * A file path which points to a packed single-channel backup within
       a file, using the same format that lnd does in its channel.backup
       file.

     * A file path which points to a packed multi-channel backup within a
       file, using the same format that lnd does in its channel.backup
       file.
  

OPTIONS:
   --single_backup value  a hex encoded single channel backup obtained from exportchanbackup
   --multi_backup value   a hex encoded multi-channel backup obtained from exportchanbackup
   --single_file value    the path to a single-channel backup file
   --multi_file value     the path to a multi-channel back up file
   

Messages

lnrpc.RestoreChanBackupRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
chan_backups The channels to restore as a list of channel/backup pairs.	ChannelBackups	object	body
multi_chan_backup The channels to restore in the packed multi backup format. When using REST, this field must be encoded as base64.	bytes	string	body

lnrpc.RestoreBackupResponse

Source: lightning.proto

Field	gRPC Type	REST Type
num_restored The number of channels successfully restored.	uint32	integer

Nested Messages

lnrpc.ChannelBackup

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

lnrpc.ChannelBackups

Field	gRPC Type	REST Type
chan_backups A set of single-chan static channel backups.	ChannelBackup[]	array

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