AnchorVirtualPsbts

AnchorVirtualPsbts merges and then commits multiple virtual transactions in a single BTC level anchor transaction. This RPC should be used if the BTC level anchor transaction of the assets to be spent are encumbered by a normal key and don't require any special spending conditions. For any custom spending conditions on the BTC level, the two RPCs CommitVirtualPsbts and PublishAndLogTransfer should be used instead (which in combination do the same as this RPC but allow for more flexibility).

Source: assetwalletrpc/assetwallet.proto

gRPC

rpc AnchorVirtualPsbts (AnchorVirtualPsbtsRequest) returns (SendAssetResponse);

REST

HTTP Method	Path
POST	/v1/taproot-assets/wallet/virtual-psbt/anchor

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 = 'TAPD_DIR/data/regtest/admin.macaroon'
const TLS_PATH = 'TAPD_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('assetwalletrpc/assetwallet.proto', loaderOptions);
const assetwalletrpc = grpc.loadPackageDefinition(packageDefinition).assetwalletrpc;
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 assetwalletrpc.AssetWallet(GRPC_HOST, creds);
let request = {
  virtual_psbts: <bytes>,
};
client.anchorVirtualPsbts(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "transfer": <AssetTransfer>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the assetwalletrpc/assetwallet.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import assetwallet_pb2 as assetwalletrpc, assetwallet_pb2_grpc as assetwalletstub

GRPC_HOST = 'localhost:10029'
MACAROON_PATH = 'TAPD_DIR/data/regtest/admin.macaroon'
TLS_PATH = 'TAPD_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 = assetwalletstub.AssetWalletStub(channel)
request = assetwalletrpc.AnchorVirtualPsbtsRequest(
  virtual_psbts=<bytes>,
)
response = stub.AnchorVirtualPsbts(request)
print(response)
# {
#    "transfer": <AssetTransfer>,
# }

grpcurl

# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightninglabs/taproot-assets
GRPC_HOST=localhost:10029
TAPD_DIR=~/.tapd
TAPD_SOURCE=path/to/taproot-assets
NETWORK=mainnet
MACAROON_PATH="$TAPD_DIR/data/$NETWORK/admin.macaroon"
TLS_PATH="$TAPD_DIR/tls.cert"

grpcurl \
    -import-path $TAPD_SOURCE/taprpc/ \
    -proto assetwalletrpc/assetwallet.proto \
    -cacert $TLS_PATH \
    -H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "virtual_psbts": BASE64_ENCODED_VALUE }' \
    $GRPC_HOST \
    assetwalletrpc.AssetWallet/AnchorVirtualPsbts

REST

Javascript

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

const REST_HOST = 'localhost:8089'
const MACAROON_PATH = 'TAPD_DIR/data/regtest/admin.macaroon'

let requestBody = {
  virtual_psbts: <array>, // <bytes> (base64 encoded)
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/wallet/virtual-psbt/anchor`,
  // 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:
//  {
//    "transfer": <object>, // <AssetTransfer> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8089'
MACAROON_PATH = 'TAPD_DIR/data/regtest/admin.macaroon'
TLS_PATH = 'TAPD_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/taproot-assets/wallet/virtual-psbt/anchor'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'virtual_psbts': base64.b64encode(<bytes>),
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "transfer": <AssetTransfer>,
# }

curl

REST_HOST=localhost:8089
TAPD_DIR=~/.tapd
NETWORK=mainnet
MACAROON_PATH="$TAPD_DIR/data/$NETWORK/admin.macaroon"
TLS_PATH="$TAPD_DIR/tls.cert"

curl -X POST \
    --cacert $TLS_PATH \
    -H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "virtual_psbts": BASE64_ENCODED_VALUE }' \
    https://$REST_HOST/v1/taproot-assets/wallet/virtual-psbt/anchor

Messages

assetwalletrpc.AnchorVirtualPsbtsRequest

Source: assetwalletrpc/assetwallet.proto

Field	gRPC Type	REST Type	REST Placement
virtual_psbts The list of virtual transactions that should be merged and committed to in the BTC level anchor transaction.	bytes[]	array	body

taprpc.SendAssetResponse

Source: taprootassets.proto

Field	gRPC Type	REST Type
transfer The transfer that was created to send assets to one or more addresses.	AssetTransfer	object

Nested Messages

taprpc.AssetTransfer

Field	gRPC Type	REST Type
transfer_timestamp The timestamp of the transfer in UTC Unix time seconds.	int64	string
anchor_tx_hash The new transaction that commits to the set of Taproot Assets found at the above new anchor point. Note that this is in raw byte format, not the reversed hex string format that is used for displayed txids. When listing assets on the CLI we purposefully use the display format so it is easier to copy and paste into other tools.	bytes	string
anchor_tx_height_hint The height hint of the anchor transaction. This is the height at which the anchor transaction was published, so the actual inclusion height will be greater than this value.	uint32	integer
anchor_tx_chain_fees The total fees paid by the anchor transaction in satoshis.	int64	string
inputs Describes the set of spent assets.	TransferInput[]	array
outputs Describes the set of newly created asset outputs.	TransferOutput[]	array
anchor_tx_block_hash The block hash of the blockchain block that contains the anchor transaction. If this value is unset, the anchor transaction is unconfirmed.	ChainHash	object
anchor_tx_block_height The block height of the blockchain block that contains the anchor transaction. If the anchor transaction is still unconfirmed, this value will be 0.	uint32	integer
label An optional short label for the transfer. This label can be used to track the progress of the transfer via the logs or an event subscription. Multiple transfers can share the same label.	string	string
anchor_tx The L1 transaction that anchors the Taproot Asset commitment where the asset resides.	bytes	string

taprpc.ChainHash

Field	gRPC Type	REST Type
hash The raw hash value in byte format. This format is optimized for programmatic use, particularly for Go developers, enabling easy integration with other RPC calls or binary operations.	bytes	string
hash_str The byte-reversed hash value as a hexadecimal string. This format is intended for human interaction, making it easy to copy, paste, and use in contexts like command-line arguments or configuration files.	string	string

taprpc.TransferInput

Field	gRPC Type	REST Type
anchor_point The old/current location of the Taproot Asset commitment that was spent as an input.	string	string
asset_id The ID of the asset that was spent.	bytes	string
script_key The script key of the asset that was spent.	bytes	string
amount The amount of the asset that was spent.	uint64	string

taprpc.TransferOutput

Field	gRPC Type	REST Type
anchor The transfer output's on-chain anchor information, which contains the BTC-level output information that anchors the Taproot Asset commitment for this output.	TransferOutputAnchor	object
script_key The script key of the asset that was created.	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. If true, the asset will be shown in the wallet balance.	bool	boolean
amount The amount of the asset that was created in this output.	uint64	string
new_proof_blob The new individual transition proof (not a full proof file) that proves the inclusion of the new asset within the new AnchorTx.	bytes	string
split_commit_root_hash The split commitment root hash of the asset that was created in this output. This is only set if the asset is a split root output, meaning that the asset is a split root output that carries the change from a split or a tombstone from a non-interactive full value send output.	bytes	string
output_type The type of the output. This is used to distinguish between a simple output that is not a split root and does not carry passive assets, and a split root output that carries the change from a split or a tombstone from a non-interactive full value send output.	OutputType	string
asset_version The asset version of the output. This is used to determine how the asset is encoded in the Taproot Asset commitment tree.	AssetVersion	string
lock_time The lock time of the output, which is an optional field that can be set to delay the spending of the output until a certain time in the future.	uint64	string
relative_lock_time The relative lock time of the output, which is an optional field that can be set to delay the spending of the output relative to the block height at which the output is confirmed.	uint64	string
proof_delivery_status The delivery status of the proof associated with this output.	ProofDeliveryStatus	string
asset_id The asset ID of the asset that was created in this output.	bytes	string
proof_courier_addr The proof courier address that was used to deliver the proof for this output.	string	string
tap_addr The Taproot Asset address that was used to create the output. This is only set for new outputs for tapd versions that support the address V2 format. For older versions, this field will be empty.	string	string

taprpc.TransferOutputAnchor

Field	gRPC Type	REST Type
outpoint The new location of the Taproot Asset commitment that was created on chain.	string	string
value The anchor transaction output's value in satoshis.	int64	string
internal_key The anchor transaction output's internal key, which is the Taproot internal key of the on-chain output.	bytes	string
taproot_asset_root The Taproot Asset root commitment hash, which is the root of the Taproot Asset commitment tree for the asset that was created.	bytes	string
merkle_root The Taproot merkle root hash committed to by the outpoint of this output. If there is no Tapscript sibling, this is equal to the Taproot Asset root commitment hash. If there is a Tapscript sibling, this is the tap branch root hash of the Taproot Asset root hash and the tapscript sibling.	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
num_passive_assets The number of passive assets that were committed to this output. Passive assets are assets that are not actively spent, but are instead passively carried along with the main asset and re-anchored in the anchor output.	uint32	integer
pk_script The actual output's script, which is the P2TR script for the final Taproot output key created by this transfer output.	bytes	string

Enums

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.OutputType

Name	Number
OUTPUT_TYPE_SIMPLE OUTPUT_TYPE_SIMPLE is a plain full-value or split output that is not a split root and does not carry passive assets. In case of a split, the asset of this output has a split commitment.	0
OUTPUT_TYPE_SPLIT_ROOT OUTPUT_TYPE_SPLIT_ROOT is a split root output that carries the change from a split or a tombstone from a non-interactive full value send output. In either case, the asset of this output has a tx witness.	1

taprpc.ProofDeliveryStatus

Name	Number
PROOF_DELIVERY_STATUS_NOT_APPLICABLE Delivery is not applicable; the proof will not be delivered.	0
PROOF_DELIVERY_STATUS_COMPLETE The proof has been successfully delivered.	1
PROOF_DELIVERY_STATUS_PENDING The proof is pending delivery. This status indicates that the proof has not yet been delivered successfully. One or more attempts at proof delivery may have been made.	2