SubscribeReceiveEvents

SubscribeReceiveEvents allows a caller to subscribe to receive events for incoming asset transfers.

Source: taprootassets.proto

gRPC

info

This is a server-streaming RPC

rpc SubscribeReceiveEvents (SubscribeReceiveEventsRequest) returns (stream ReceiveEvent);

REST

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

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_addr: <string>,
  start_timestamp: <int64>,
};
let call = client.subscribeReceiveEvents(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>,
//    "address": <Addr>,
//    "outpoint": <string>,
//    "status": <AddrEventStatus>,
//    "confirmation_height": <uint32>,
//    "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.SubscribeReceiveEventsRequest(
  filter_addr=<string>,
  start_timestamp=<int64>,
)
for response in stub.SubscribeReceiveEvents(request):
  print(response)
# {
#    "timestamp": <int64>,
#    "address": <Addr>,
#    "outpoint": <string>,
#    "status": <AddrEventStatus>,
#    "confirmation_height": <uint32>,
#    "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_addr: <string>, // <string> 
  start_timestamp: <string>, // <int64> 
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/events/asset-receive`,
  // 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> 
//    "address": <object>, // <Addr> 
//    "outpoint": <string>, // <string> 
//    "status": <string>, // <AddrEventStatus> 
//    "confirmation_height": <integer>, // <uint32> 
//    "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-receive?method=POST`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
  filter_addr: <string>, // <string> 
  start_timestamp: <int64>, // <int64> 
};
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>
//    "address": <object>, // <Addr>
//    "outpoint": <string>, // <string>
//    "status": <string>, // <AddrEventStatus>
//    "confirmation_height": <integer>, // <uint32>
//    "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-receive'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'filter_addr': <string>,
  'start_timestamp': <int64>,
}
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>,
#    "address": <Addr>,
#    "outpoint": <string>,
#    "status": <AddrEventStatus>,
#    "confirmation_height": <uint32>,
#    "error": <string>,
# }

Shell

$ tapcli events receive --help

NAME:
   tapcli events receive - Subscribe to events around receiving inbound assets

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

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

OPTIONS:
   --addr value  (optional) the address to receive events for; if not set, events for all addresses will be shown
   

Messages

taprpc.SubscribeReceiveEventsRequest

Source: taprootassets.proto

Field	gRPC Type	REST Type	REST Placement
filter_addr Filter receives by a specific address. Leave empty to get all receive events for all addresses.	string	string	body
start_timestamp The start time as a Unix timestamp in microseconds. If not set (default value 0), the daemon will start streaming events from the current time.	int64	string	body

taprpc.ReceiveEvent

Source: taprootassets.proto

Field	gRPC Type	REST Type
timestamp Event creation timestamp (Unix timestamp in microseconds).	int64	string
address The address that received the asset.	Addr	object
outpoint The outpoint of the transaction that was used to receive the asset.	string	string
status The status of the event. If error below is set, then the status is the state that lead to the error during its execution.	AddrEventStatus	string
confirmation_height The height of the block the asset receive transaction was mined in. This is only set if the status is ADDR_EVENT_STATUS_TRANSACTION_CONFIRMED or later.	uint32	integer
error An optional error, indicating that executing the status above 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

Enums

taprpc.AddrEventStatus

Name	Number
ADDR_EVENT_STATUS_UNKNOWN	0
ADDR_EVENT_STATUS_TRANSACTION_DETECTED	1
ADDR_EVENT_STATUS_TRANSACTION_CONFIRMED	2
ADDR_EVENT_STATUS_PROOF_RECEIVED	3
ADDR_EVENT_STATUS_COMPLETED	4

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