SyncUniverse

SyncUniverse takes host information for a remote Universe server, then attempts to synchronize either only the set of specified asset_ids, or all assets if none are specified. The sync process will attempt to query for the latest known root for each asset, performing tree based reconciliation to arrive at a new shared root.

Source: universerpc/universe.proto

gRPC

rpc SyncUniverse (SyncRequest) returns (SyncResponse);

REST

HTTP Method	Path
POST	/v1/taproot-assets/universe/sync

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('universerpc/universe.proto', loaderOptions);
const universerpc = grpc.loadPackageDefinition(packageDefinition).universerpc;
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 universerpc.Universe(GRPC_HOST, creds);
let request = {
  universe_host: <string>,
  sync_mode: <UniverseSyncMode>,
  sync_targets: <SyncTarget>,
};
client.syncUniverse(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "synced_universes": <SyncedUniverse>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the universerpc/universe.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import universe_pb2 as universerpc, universe_pb2_grpc as universestub

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 = universestub.UniverseStub(channel)
request = universerpc.SyncRequest(
  universe_host=<string>,
  sync_mode=<UniverseSyncMode>,
  sync_targets=<SyncTarget>,
)
response = stub.SyncUniverse(request)
print(response)
# {
#    "synced_universes": <SyncedUniverse>,
# }

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 = {
  universe_host: <string>, // <string> 
  sync_mode: <string>, // <UniverseSyncMode> 
  sync_targets: <array>, // <SyncTarget> 
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/universe/sync`,
  // 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:
//  {
//    "synced_universes": <array>, // <SyncedUniverse> 
//  }

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/universe/sync'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'universe_host': <string>,
  'sync_mode': <UniverseSyncMode>,
  'sync_targets': <SyncTarget>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "synced_universes": <SyncedUniverse>,
# }

Shell

$ tapcli universe sync --help

NAME:
   tapcli universe sync - synchronize universe state with a remote instance

USAGE:
   tapcli universe sync [command options] [arguments...]

DESCRIPTION:
   Attempt to sync Universe state with a remote Universe

OPTIONS:
   --universe_host value  the host:port or just host of the remote universe
   --asset_id value       the asset ID of the sync with the universe
   --group_key value      the group key of sync with the universe
   --proof_type value     the type of proof to sync either 'issuance' or 'transfer' (default: "issuance")
   

Messages

universerpc.SyncRequest

Source: universerpc/universe.proto

Field	gRPC Type	REST Type	REST Placement
universe_host TODO(roasbeef): accept connection type? so can pass along self-signed cert, also brontide based RPC handshake	string	string	body
sync_mode The sync mode. This determines what type of proofs are synced.	UniverseSyncMode	string	body
sync_targets The set of assets to sync. If none are specified, then all assets are synced.	SyncTarget[]	array	body

universerpc.SyncResponse

Source: universerpc/universe.proto

Field	gRPC Type	REST Type
synced_universes The set of synced asset Universes.	SyncedUniverse[]	array

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

universerpc.AssetLeaf

Field	gRPC Type	REST Type
asset The asset included in the leaf.	Asset	object
proof The asset issuance or transfer proof, which proves that the asset specified above was issued or transferred properly. This is always just an individual mint/transfer proof and never a proof file.	bytes	string

universerpc.ID

Field	gRPC Type	REST Type
asset_id The 32-byte asset ID specified as raw bytes (gRPC only).	bytes	string
asset_id_str The 32-byte asset ID encoded as a hex string (use this for REST).	string	string
group_key The 32-byte asset group key specified as raw bytes (gRPC only).	bytes	string
group_key_str The 32-byte asset group key encoded as hex string (use this for REST).	string	string
proof_type Nested REST Parameters proof_type: string in query	ProofType	string

universerpc.MerkleSumNode

Field	gRPC Type	REST Type
root_hash The MS-SMT root hash for the branch node.	bytes	string
root_sum The root sum of the branch node. This is hashed to create the root_hash along with the left and right siblings. This value represents the total known supply of the asset.	int64	string

universerpc.SyncedUniverse

Field	gRPC Type	REST Type
old_asset_root The old Universe root for the synced asset.	UniverseRoot	object
new_asset_root The new Universe root for the synced asset.	UniverseRoot	object
new_asset_leaves The set of new asset leaves that were synced.	AssetLeaf[]	array

universerpc.SyncTarget

Field	gRPC Type	REST Type
id	ID	object

universerpc.UniverseRoot

Field	gRPC Type	REST Type
id	ID	object
mssmt_root The merkle sum sparse merkle tree root associated with the above universe ID.	MerkleSumNode	object
asset_name The name of the asset.	string	string
amounts_by_asset_id A map of hex encoded asset IDs to the number of units minted for that asset. This only contains more than one entry for grouped assets and in that case represents the whole list of assets currently known to exist within the group. For single (non-grouped) assets, this is equal to the asset ID above and the sum in the mssmt_root. A hex encoded string is used as the map key because gRPC does not support using raw bytes for a map key.	AmountsByAssetIdEntry[]	object

universerpc.UniverseRoot.AmountsByAssetIdEntry

Field	gRPC Type	REST Type
key	string	unknown
value	uint64	unknown

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

universerpc.ProofType

Name	Number
PROOF_TYPE_UNSPECIFIED	0
PROOF_TYPE_ISSUANCE	1
PROOF_TYPE_TRANSFER	2

universerpc.UniverseSyncMode

Name	Number
SYNC_ISSUANCE_ONLY A sync node that indicates that only new asset creation (minting) proofs should be synced.	0
SYNC_FULL A syncing mode that indicates that all asset proofs should be synced. This includes normal transfers as well.	1