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.InsertProof 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 The asset transfer that was registered.	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
block_timestamp The UTC Unix timestamp of the block containing the anchor transaction.	int64	string

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 The asset's previous witnesses, which either contain the spending witness stack (usually a signature) or the split commitment witness (which is used to prove the split commitment of a split asset).	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_knowndeprecated Deprecated, use script_key_type instead! 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_pathdeprecated Deprecated, use script_key_type instead! 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
script_key_type The type of the script key. This type is either user-declared when custom script keys are added, or automatically determined by the daemon for standard operations (e.g. BIP-86 keys, burn keys, tombstone keys, channel related keys).	ScriptKeyType	string

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 The previous input's anchor point, which is the on-chain outpoint the asset was anchored to.	string	string
asset_id The asset ID of the asset that was spent as an input.	bytes	string
script_key The script key of the asset that was spent as an input.	bytes	string
amount The amount of the asset that was spent as an input.	uint64	string

taprpc.PrevWitness

Field	gRPC Type	REST Type
prev_id The previous input asset that this witness is for.	PrevInputAsset	object
tx_witness The witness stack that is used to prove the asset owner's authorization to spend an asset. This is only set if the asset is the root asset of an asset split.	bytes[]	array
split_commitment The split commitment that is used to prove the split commitment of a split asset. This is only set if the asset is a split asset.	SplitCommitment	object

taprpc.SplitCommitment

Field	gRPC Type	REST Type
root_asset The root asset that contains the transaction witness that authorizes the spend of the 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

taprpc.ScriptKeyType

Name	Number
SCRIPT_KEY_UNKNOWN The type of script key is not known. This should only be stored for assets where we don't know the internal key of the script key (e.g. for imported proofs).	0
SCRIPT_KEY_BIP86 The script key is a normal BIP-86 key. This means that the internal key is turned into a Taproot output key by applying a BIP-86 tweak to it.	1
SCRIPT_KEY_SCRIPT_PATH_EXTERNAL The script key is a key that contains a script path that is defined by the user and is therefore external to the tapd wallet. Spending this key requires providing a specific witness and must be signed through the vPSBT signing flow.	2
SCRIPT_KEY_BURN The script key is a specific un-spendable key that indicates a burnt asset. Assets with this key type can never be spent again, as a burn key is a tweaked NUMS key that nobody knows the private key for.	3
SCRIPT_KEY_TOMBSTONE The script key is a specific un-spendable key that indicates a tombstone output. This is only the case for zero-value assets that result from a non-interactive (TAP address) send where no change was left over.	4
SCRIPT_KEY_CHANNEL The script key is used for an asset that resides within a Taproot Asset Channel. That means the script key is either a funding key (OP_TRUE), a commitment output key (to_local, to_remote, htlc), or a HTLC second-level transaction output key. Keys related to channels are not shown in asset balances (unless specifically requested) and are never used for coin selection.	5
SCRIPT_KEY_UNIQUE_PEDERSEN The script key is derived using the asset ID and a single leaf that contains an un-spendable Pedersen commitment key `(OP_CHECKSIG <NUMS_key + asset_id * G>)`. This can be used to create unique script keys for each virtual packet in the fragment, to avoid proof collisions in the universe, where the script keys should be spendable by a hardware wallet that only supports miniscript policies for signing P2TR outputs.	6