ImportTapscript

ImportTapscript imports a Taproot script and internal key and adds the resulting Taproot output key as a watch-only output script into the wallet. For BIP-0086 style Taproot keys (no root hash commitment and no script spend path) use ImportPublicKey.

NOTE: Events (deposits/spends) for a key will only be detected by lnd if they happen after the import. Rescans to detect past events will be supported later on.

NOTE: Taproot keys imported through this RPC currently cannot be used for funding PSBTs. Only tracking the balance and UTXOs is currently supported.

Source: walletrpc/walletkit.proto

gRPC

rpc ImportTapscript (ImportTapscriptRequest) returns (ImportTapscriptResponse);

REST

HTTP Method	Path
POST	/v2/wallet/tapscript/import

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', 'walletrpc/walletkit.proto'], loaderOptions);
const walletrpc = grpc.loadPackageDefinition(packageDefinition).walletrpc;
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 walletrpc.WalletKit(GRPC_HOST, creds);
let request = {
  internal_public_key: <bytes>,
  full_tree: <TapscriptFullTree>,
  partial_reveal: <TapscriptPartialReveal>,
  root_hash_only: <bytes>,
  full_key_only: <bool>,
};
client.importTapscript(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "p2tr_address": <string>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the walletrpc/walletkit.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import walletkit_pb2 as walletrpc, walletkit_pb2_grpc as walletkitstub

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 = walletkitstub.WalletKitStub(channel)
request = walletrpc.ImportTapscriptRequest(
  internal_public_key=<bytes>,
  full_tree=<TapscriptFullTree>,
  partial_reveal=<TapscriptPartialReveal>,
  root_hash_only=<bytes>,
  full_key_only=<bool>,
)
response = stub.ImportTapscript(request)
print(response)
# {
#    "p2tr_address": <string>,
# }

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 = {
  internal_public_key: <string>, // <bytes> (base64 encoded)
  full_tree: <object>, // <TapscriptFullTree> 
  partial_reveal: <object>, // <TapscriptPartialReveal> 
  root_hash_only: <string>, // <bytes> (base64 encoded)
  full_key_only: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v2/wallet/tapscript/import`,
  // 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:
//  {
//    "p2tr_address": <string>, // <string> 
//  }

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}/v2/wallet/tapscript/import'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'internal_public_key': base64.b64encode(<bytes>),
  'full_tree': <TapscriptFullTree>,
  'partial_reveal': <TapscriptPartialReveal>,
  'root_hash_only': base64.b64encode(<bytes>),
  'full_key_only': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "p2tr_address": <string>,
# }

Shell

# There is no CLI command for this RPC

Messages

walletrpc.ImportTapscriptRequest

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type	REST Placement
internal_public_key The internal public key, serialized as 32-byte x-only public key.	bytes	string	body
full_tree The full script tree with all individual leaves is known and the root hash can be constructed from the full tree directly.	TapscriptFullTree	object	body
partial_reveal Only a single script leaf is known. To construct the root hash, the full inclusion proof must also be provided.	TapscriptPartialReveal	object	body
root_hash_only Only the root hash of the Taproot script tree (or other form of Taproot commitment) is known.	bytes	string	body
full_key_only Only the final, tweaked Taproot key is known and no additional information about the internal key or type of tweak that was used to derive it. When this is set, the wallet treats the key in internal_public_key as the Taproot key directly. This can be useful for tracking arbitrary Taproot outputs without the goal of ever being able to spend from them through the internal wallet.	bool	boolean	body

walletrpc.ImportTapscriptResponse

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type
p2tr_address The resulting pay-to-Taproot address that represents the imported internal key with the script committed to it.	string	string

Nested Messages

walletrpc.TapLeaf

Field	gRPC Type	REST Type
leaf_version The leaf version. Should be 0xc0 (192) in case of a SegWit v1 script.	uint32	integer
script The script of the tap leaf.	bytes	string

walletrpc.TapscriptFullTree

Field	gRPC Type	REST Type
all_leaves The complete, ordered list of all tap leaves of the tree.	TapLeaf[]	array

walletrpc.TapscriptPartialReveal

Field	gRPC Type	REST Type
revealed_leaf The tap leaf that is known and will be revealed.	TapLeaf	object
full_inclusion_proof The BIP-0341 serialized inclusion proof that is required to prove that the revealed leaf is part of the tree. This contains 0..n blocks of 32 bytes. If the tree only contained a single leaf (which is the revealed leaf), this can be empty.	bytes	string