SubscribeSendEvents

SubscribeSendEvents allows a caller to subscribe to send events for outgoing asset transfers.

Source: taprootassets.proto

gRPC

info

This is a server-streaming RPC

rpc SubscribeSendEvents (SubscribeSendEventsRequest) returns (stream SendEvent);

REST

HTTP Method	Path
POST	/v1/taproot-assets/events/asset-send

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 = {
  filter_script_key: <bytes>,
};
let call = client.subscribeSendEvents(request);
call.on('data', function(response) {
  // A response was received from the server.
  console.log(response);
});
call.on('status', function(status) {
  // The current status of the stream.
});
call.on('end', function() {
  // The server has closed the stream.
});
// Console output:
//  {
//    "timestamp": <int64>,
//    "send_state": <string>,
//    "parcel_type": <ParcelType>,
//    "addresses": <Addr>,
//    "virtual_packets": <bytes>,
//    "passive_virtual_packets": <bytes>,
//    "anchor_transaction": <AnchorTransaction>,
//    "transfer": <AssetTransfer>,
//    "error": <string>,
//  }

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.SubscribeSendEventsRequest(
  filter_script_key=<bytes>,
)
for response in stub.SubscribeSendEvents(request):
  print(response)
# {
#    "timestamp": <int64>,
#    "send_state": <string>,
#    "parcel_type": <ParcelType>,
#    "addresses": <Addr>,
#    "virtual_packets": <bytes>,
#    "passive_virtual_packets": <bytes>,
#    "anchor_transaction": <AnchorTransaction>,
#    "transfer": <AssetTransfer>,
#    "error": <string>,
# }

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 = {
  filter_script_key: <string>, // <bytes> (base64 encoded)
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/events/asset-send`,
  // 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:
//  {
//    "timestamp": <string>, // <int64> 
//    "send_state": <string>, // <string> 
//    "parcel_type": <string>, // <ParcelType> 
//    "addresses": <array>, // <Addr> 
//    "virtual_packets": <array>, // <bytes> 
//    "passive_virtual_packets": <array>, // <bytes> 
//    "anchor_transaction": <object>, // <AnchorTransaction> 
//    "transfer": <object>, // <AssetTransfer> 
//    "error": <string>, // <string> 
//  }



// --------------------------
// Example with websockets:
// --------------------------
const WebSocket = require('ws');
const fs = require('fs');

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

let ws = new WebSocket(`wss://${REST_HOST}/v1/taproot-assets/events/asset-send?method=POST`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
  filter_script_key: <bytes>, // <bytes> (base64 encoded)
};
ws.on('open', function() {
    ws.send(JSON.stringify(requestBody));
});
ws.on('error', function(err) {
    console.log('Error: ' + err);
});
ws.on('message', function(body) {
    console.log(body);
});
// Console output:
//  {
//    "timestamp": <string>, // <int64>
//    "send_state": <string>, // <string>
//    "parcel_type": <string>, // <ParcelType>
//    "addresses": <array>, // <Addr>
//    "virtual_packets": <array>, // <bytes>
//    "passive_virtual_packets": <array>, // <bytes>
//    "anchor_transaction": <object>, // <AnchorTransaction>
//    "transfer": <object>, // <AssetTransfer>
//    "error": <string>, // <string>
//  }

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/events/asset-send'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'filter_script_key': base64.b64encode(<bytes>),
}
r = requests.post(url, headers=headers, stream=True, data=json.dumps(data), verify=TLS_PATH)
for raw_response in r.iter_lines():
  json_response = json.loads(raw_response)
  print(json_response)
# {
#    "timestamp": <int64>,
#    "send_state": <string>,
#    "parcel_type": <ParcelType>,
#    "addresses": <Addr>,
#    "virtual_packets": <bytes>,
#    "passive_virtual_packets": <bytes>,
#    "anchor_transaction": <AnchorTransaction>,
#    "transfer": <AssetTransfer>,
#    "error": <string>,
# }

Shell

$ tapcli events send --help

NAME:
   tapcli events send - Subscribe to events around sending outbound assets

USAGE:
   tapcli events send [command options] [arguments...]

DESCRIPTION:
   Get live updates on the status of outbound asset transfers to the local node. This command will block until aborted manually by hitting Ctrl+C.

OPTIONS:
   --script_key value  (optional) the script key to receive events for; if not set, events for all transfers will be shown
   

Messages

taprpc.SubscribeSendEventsRequest

Source: taprootassets.proto

Field	gRPC Type	REST Type	REST Placement
filter_script_key Filter send events by a specific recipient script key. Leave empty to get all receive events for all parcels.	bytes	string	body

taprpc.SendEvent

Source: taprootassets.proto

Field	gRPC Type	REST Type
timestamp Execute timestamp (Unix timestamp in microseconds).	int64	string
send_state The send state that was executed successfully. If error below is set, then the send_state is the state that lead to the error during its execution.	string	string
parcel_type The type of the outbound send parcel.	ParcelType	string
addresses The list of addresses the parcel sends to (recipient addresses only, not including change going back to own wallet). This is only set for parcels of type PARCEL_TYPE_ADDRESS.	Addr[]	array
virtual_packets The virtual packets that are part of the parcel.	bytes[]	array
passive_virtual_packets The passive virtual packets that are carried along with the parcel. This is empty if there were no other assets in the input commitment that is being spent with the "active" virtual packets above.	bytes[]	array
anchor_transaction The Bitcoin on-chain anchor transaction that commits the sent assets on-chain. This is only set after the send state SEND_STATE_ANCHOR_SIGN.	AnchorTransaction	object
transfer The final transfer as it will be stored in the database. This is only set after the send state SEND_STATE_LOG_COMMITMENT.	AssetTransfer	object
error An optional error, indicating that executing the send_state failed.	string	string

Nested Messages

taprpc.Addr

Field	gRPC Type	REST Type
encoded The bech32 encoded Taproot Asset address.	string	string
asset_id The asset ID that uniquely identifies the asset.	bytes	string
asset_type The type of the asset.	AssetType	string
amount The total amount of the asset stored in this Taproot Asset UTXO.	uint64	string
group_key The group key of the asset (if it exists)	bytes	string
script_key The specific script key the asset must commit to in order to transfer ownership to the creator of the address.	bytes	string
internal_key The internal key used for the on-chain output.	bytes	string
tapscript_sibling The optional serialized tapscript sibling preimage to use for the receiving asset. This is usually empty as it is only needed when there should be an additional script path in the Taproot tree alongside the Taproot Asset commitment of the asset.	bytes	string
taproot_output_key The tweaked internal key that commits to the asset and represents the on-chain output key the Bitcoin transaction must send to in order to transfer assets described in this address.	bytes	string
proof_courier_addr The address of the proof courier service used in proof transfer.	string	string
asset_version The asset version of the address.	AssetVersion	string

taprpc.AnchorTransaction

Field	gRPC Type	REST Type
anchor_psbt	bytes	string
change_output_index The index of the (added) change output or -1 if no change was left over.	int32	integer
chain_fees_sats The total number of satoshis in on-chain fees paid by the anchor transaction.	int64	string
target_fee_rate_sat_kw The fee rate in sat/kWU that was targeted by the anchor transaction.	int32	integer
lnd_locked_utxos The list of UTXO lock leases that were acquired for the inputs in the funded PSBT packet from lnd. Only inputs added to the PSBT by this RPC are locked, inputs that were already present in the PSBT are not locked.	OutPoint[]	array
final_tx The final, signed anchor transaction that was broadcast to the network.	bytes	string

taprpc.AssetTransfer

Field	gRPC Type	REST Type
transfer_timestamp	int64	string
anchor_tx_hash The new transaction that commits to the set of Taproot Assets found at the above new anchor point.	bytes	string
anchor_tx_height_hint	uint32	integer
anchor_tx_chain_fees	int64	string
inputs Describes the set of spent assets.	TransferInput[]	array
outputs Describes the set of newly created asset outputs.	TransferOutput[]	array

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.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	TransferOutputAnchor	object
script_key	bytes	string
script_key_is_local	bool	boolean
amount	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	bytes	string
output_type	OutputType	string
asset_version	AssetVersion	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	int64	string
internal_key	bytes	string
taproot_asset_root	bytes	string
merkle_root	bytes	string
tapscript_sibling	bytes	string
num_passive_assets	uint32	integer

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

Name	Number
PARCEL_TYPE_ADDRESS The parcel is an address parcel.	0
PARCEL_TYPE_PRE_SIGNED The parcel type is a pre-signed parcel where the virtual transactions are signed outside of the send state machine. Parcels of this type will only get send states starting from SEND_STATE_ANCHOR_SIGN.	1
PARCEL_TYPE_PENDING The parcel is pending and was resumed on the latest restart of the daemon. The original parcel type (address or pre-signed) is not known anymore, as it's not relevant for the remaining steps. Parcels of this type will only get send states starting from SEND_STATE_BROADCAST.	2