RegisterTransfer

RegisterTransfer informs the daemon about a new inbound transfer that has happened. This is used for interactive transfers where no TAP address is involved and the recipient is aware of the transfer through an out-of-band protocol but the daemon hasn't been informed about the completion of the transfer. For this to work, the proof must already be in the recipient's local universe (e.g. through the use of the universerpc.ImportProof RPC or the universe proof courier and universe sync mechanisms) and this call simply instructs the daemon to detect the transfer as an asset it owns.

Source: taprootassets.proto

gRPC

rpc RegisterTransfer (RegisterTransferRequest) returns (RegisterTransferResponse);

REST

HTTP Method	Path
POST	/v1/taproot-assets/assets/transfers/register

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10029'
const MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
const TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('taprootassets.proto', loaderOptions);
const taprpc = grpc.loadPackageDefinition(packageDefinition).taprpc;
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 taprpc.TaprootAssets(GRPC_HOST, creds);
let request = {
  asset_id: <bytes>,
  group_key: <bytes>,
  script_key: <bytes>,
  outpoint: <OutPoint>,
};
client.registerTransfer(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "registered_asset": <Asset>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the taprootassets.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import taprootassets_pb2 as taprpc, taprootassets_pb2_grpc as taprootassetsstub

GRPC_HOST = 'localhost:10029'
MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
TLS_PATH = 'TAPROOT-ASSETS_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 = taprootassetsstub.TaprootAssetsStub(channel)
request = taprpc.RegisterTransferRequest(
  asset_id=<bytes>,
  group_key=<bytes>,
  script_key=<bytes>,
  outpoint=<OutPoint>,
)
response = stub.RegisterTransfer(request)
print(response)
# {
#    "registered_asset": <Asset>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8089'
const MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'

let requestBody = {
  asset_id: <string>, // <bytes> (base64 encoded)
  group_key: <string>, // <bytes> (base64 encoded)
  script_key: <string>, // <bytes> (base64 encoded)
  outpoint: <object>, // <OutPoint> 
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/assets/transfers/register`,
  // 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:
//  {
//    "registered_asset": <object>, // <Asset> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8089'
MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/taproot-assets/assets/transfers/register'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'asset_id': base64.b64encode(<bytes>),
  'group_key': base64.b64encode(<bytes>),
  'script_key': base64.b64encode(<bytes>),
  'outpoint': <OutPoint>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "registered_asset": <Asset>,
# }

Shell

# There is no CLI command for this RPC

Messages

taprpc.RegisterTransferRequest

Source: taprootassets.proto

Field	gRPC Type	REST Type	REST Placement
asset_id The asset ID of the asset to register the transfer for.	bytes	string	body
group_key The optional group key of the asset to register the transfer for.	bytes	string	body
script_key The script key of the asset to register the transfer for.	bytes	string	body
outpoint The outpoint of the transaction that was used to receive the asset.	OutPoint	object	body

taprpc.RegisterTransferResponse

Source: taprootassets.proto

Field	gRPC Type	REST Type
registered_asset	Asset	object

Nested Messages

taprpc.AnchorInfo

Field	gRPC Type	REST Type
anchor_tx The transaction that anchors the Taproot Asset commitment where the asset resides.	bytes	string
anchor_block_hash The block hash the contains the anchor transaction above.	string	string
anchor_outpoint The outpoint (txid:vout) that stores the Taproot Asset commitment.	string	string
internal_key The raw internal key that was used to create the anchor Taproot output key.	bytes	string
merkle_root The Taproot merkle root hash of the anchor output the asset was committed to. If there is no Tapscript sibling, this is equal to the Taproot Asset root commitment hash.	bytes	string
tapscript_sibling The serialized preimage of a Tapscript sibling, if there was one. If this is empty, then the merkle_root hash is equal to the Taproot root hash of the anchor output.	bytes	string
block_height The height of the block which contains the anchor transaction.	uint32	integer

taprpc.Asset

Field	gRPC Type	REST Type
version The version of the Taproot Asset.	AssetVersion	string
asset_genesis The base genesis information of an asset. This information never changes.	GenesisInfo	object
amount The total amount of the asset stored in this Taproot Asset UTXO.	uint64	string
lock_time An optional locktime, as with Bitcoin transactions.	int32	integer
relative_lock_time An optional relative lock time, same as Bitcoin transactions.	int32	integer
script_version The version of the script, only version 0 is defined at present.	int32	integer
script_key The script key of the asset, which can be spent under Taproot semantics.	bytes	string
script_key_is_local Indicates whether the script key is known to the wallet of the lnd node connected to the Taproot Asset daemon.	bool	boolean
asset_group The information related to the key group of an asset (if it exists).	AssetGroup	object
chain_anchor Describes where in the chain the asset is currently anchored.	AnchorInfo	object
prev_witnesses	PrevWitness[]	array
is_spent Indicates whether the asset has been spent.	bool	boolean
lease_owner If the asset has been leased, this is the owner (application ID) of the lease.	bytes	string
lease_expiry If the asset has been leased, this is the expiry of the lease as a Unix timestamp in seconds.	int64	string
is_burn Indicates whether this transfer was an asset burn. If true, the number of assets in this output are destroyed and can no longer be spent.	bool	boolean
script_key_declared_known Indicates whether this script key has either been derived by the local wallet or was explicitly declared to be known by using the DeclareScriptKey RPC. Knowing the key conceptually means the key belongs to the local wallet or is at least known by a software that operates on the local wallet. The flag is never serialized in proofs, so this is never explicitly set for keys foreign to the local wallet. Therefore, if this method returns true for a script key, it means the asset with the script key will be shown in the wallet balance.	bool	boolean
script_key_has_script_path Indicates whether the script key is known to have a Tapscript spend path, meaning that the Taproot merkle root tweak is not empty. This will only ever be true if either script_key_is_local or script_key_internals_known is true as well, since the presence of a Tapscript spend path cannot be determined for script keys that aren't known to the wallet of the local tapd node.	bool	boolean
decimal_display This field defines a decimal display value that may be present. If this field is null, it means the presence of a decimal display field is unknown in the current context.	DecimalDisplay	object

taprpc.AssetGroup

Field	gRPC Type	REST Type
raw_group_key The raw group key which is a normal public key.	bytes	string
tweaked_group_key The tweaked group key, which is derived based on the genesis point and also asset type.	bytes	string
asset_witness A witness that authorizes a specific asset to be part of the asset group specified by the above key.	bytes	string
tapscript_root The root hash of a tapscript tree, which enables future issuance authorized with a script witness.	bytes	string

taprpc.DecimalDisplay

Field	gRPC Type	REST Type
decimal_display Decimal display dictates the number of decimal places to shift the amount to the left converting from Taproot Asset integer representation to a UX-recognizable fractional quantity. For example, if the decimal_display value is 2 and there's 100 of those assets, then a wallet would display the amount as "1.00". This field is intended as information for wallets that display balances and has no impact on the behavior of the daemon or any other part of the protocol. This value is encoded in the MetaData field as a JSON field, therefore it is only compatible with assets that have a JSON MetaData field.	uint32	integer

taprpc.GenesisInfo

Field	gRPC Type	REST Type
genesis_point The first outpoint of the transaction that created the asset (txid:vout).	string	string
name The name of the asset.	string	string
meta_hash The hash of the meta data for this genesis asset.	bytes	string
asset_id The asset ID that uniquely identifies the asset.	bytes	string
asset_type The type of the asset.	AssetType	string
output_index The index of the output that carries the unique Taproot Asset commitment in the genesis transaction.	uint32	integer

taprpc.OutPoint

Field	gRPC Type	REST Type
txid Raw bytes representing the transaction id.	bytes	string
output_index The index of the output on the transaction.	uint32	integer

taprpc.PrevInputAsset

Field	gRPC Type	REST Type
anchor_point	string	string
asset_id	bytes	string
script_key	bytes	string
amount	uint64	string

taprpc.PrevWitness

Field	gRPC Type	REST Type
prev_id	PrevInputAsset	object
tx_witness	bytes[]	array
split_commitment	SplitCommitment	object

taprpc.SplitCommitment

Field	gRPC Type	REST Type
root_asset	Asset	object

Enums

taprpc.AssetType

Name	Number
NORMAL Indicates that an asset is capable of being split/merged, with each of the units being fungible, even across a key asset ID boundary (assuming the key group is the same).	0
COLLECTIBLE Indicates that an asset is a collectible, meaning that each of the other items under the same key group are not fully fungible with each other. Collectibles also cannot be split or merged.	1

taprpc.AssetVersion

Name	Number
ASSET_VERSION_V0 ASSET_VERSION_V0 is the default asset version. This version will include the witness vector in the leaf for a tap commitment.	0
ASSET_VERSION_V1 ASSET_VERSION_V1 is the asset version that leaves out the witness vector from the MS-SMT leaf encoding.	1