Getting the asset identifier behind a namespace with receipts

Get the resolution for a given alias and transaction using receipts.

Background

In Catapult, accounts can link their registered namespaces to other accounts or mosaics by announcing an AliasTransaction. This feature allows you to replace long and complex identifiers with short and familiar names for your accounts and mosaics.

Imagine a ticket vendor sending tickets to their customers on the Catapult public blockchain. The company needs to send 1 0dc67fbe1cad29e3 to SCVG35-ZSPMYP-L2POZQ-JGSVEG-RYOJ3V-BNIU3U-N2E6. With aliases, it can define the same transaction as sending 1 ticketsales.event1.ticket to @alice instead.

../../_images/namespace-tickets.png

Recognizable mosaics and addresses

To ensure the transactions are being sent to the correct place with the correct mosaic, you can directly query the network about the current mosaic identifier behind a namespace by running the following snippet:

const namespace = new NamespaceId('cat.currency');

const namespaceHttp = new NamespaceHttp('http://localhost:3000');
namespaceHttp
    .getLinkedMosaicId(namespace)
    .subscribe(mosaicId => console.log(mosaicId.toHex()),
            err => console.log(err));
const namespace = new nem2_sdk_1.NamespaceId('cat.currency');
const namespaceHttp = new nem2_sdk_1.NamespaceHttp('http://localhost:3000');
namespaceHttp
    .getLinkedMosaicId(namespace)
    .subscribe(mosaicId => console.log(mosaicId.toHex()), err => console.log(err));

However, the same method cannot be used to verify transactions of the past. This is due to the facts that:

  • Transactions using aliased mosaics or accounts are stored on the blockchain using the namespace identifier, not the real address or mosaic id behind it.
  • Links are editable. The namespace owner can link its namespace to another asset.
  • Namespaces expire. The namespace link could be deleted.

At this point, you might be wondering: how then can we get the accurate relation between a namespace and its real identifier for a past transaction? The answer lies with receipts. For each block, Catapult nodes store receipts that contain every invisible state change that cannot be retrieved directly from the transaction or block header.

Prerequisites

Getting into some code

In this example, we are going to announce a TransferTransaction using cat.currency instead of the native currency mosaic id. Once the network confirms the transaction, we will get the block height where the transaction has been recorded. With this information, we will then get the namespace-mosaic relation by looking into the block receipts’.

  1. Define the mosaic you want to send. Use a linked namespace identifier (e.g. cat.currency) instead of the mosaic identifier.
const aliasedMosaic = new Mosaic(
    new NamespaceId('cat.currency'),
    UInt64.fromUint(1000000)
);
const aliasedMosaic = new nem2_sdk_1.Mosaic(new nem2_sdk_1.NamespaceId('cat.currency'), nem2_sdk_1.UInt64.fromUint(1000000));
  1. Attach the mosaic to a TransferTransaction.
const transferTransaction = TransferTransaction.create(
    Deadline.create(),
    Address.createFromRawAddress('SD5DT3-CH4BLA-BL5HIM-EKP2TA-PUKF4N-Y3L5HR-IR54'),
    [aliasedMosaic],
    PlainMessage.create('Test aliased mosaic'),
    NetworkType.MIJIN_TEST);

const privateKey = process.env.PRIVATE_KEY as string;
const account = Account.createFromPrivateKey(privateKey, NetworkType.MIJIN_TEST);
const networkGenerationHash = process.env.GENERATION_HASH as string;

const signedTransaction = account.sign(transferTransaction, networkGenerationHash);
console.log(signedTransaction.hash);
const transferTransaction = nem2_sdk_1.TransferTransaction.create(nem2_sdk_1.Deadline.create(), nem2_sdk_1.Address.createFromRawAddress('SD5DT3-CH4BLA-BL5HIM-EKP2TA-PUKF4N-Y3L5HR-IR54'), [aliasedMosaic], nem2_sdk_1.PlainMessage.create('Test aliased mosaic'), nem2_sdk_1.NetworkType.MIJIN_TEST);
const privateKey = process.env.PRIVATE_KEY;
const account = nem2_sdk_1.Account.createFromPrivateKey(privateKey, nem2_sdk_1.NetworkType.MIJIN_TEST);
const networkGenerationHash = process.env.GENERATION_HASH;
const signedTransaction = account.sign(transferTransaction, networkGenerationHash);
console.log(signedTransaction.hash);
  1. Announce the TransferTransaction, and wait until it is confirmed.
const nodeUrl = 'http://localhost:3000';
const receiptHttp = new ReceiptHttp(nodeUrl);
const transactionHttp = new TransactionHttp(nodeUrl);
const listener = new Listener(nodeUrl);

listener.open().then(() => {

    transactionHttp
        .announce(signedTransaction)
        .subscribe(x => console.log(x), err => console.error(err));
const nodeUrl = 'http://localhost:3000';
const receiptHttp = new nem2_sdk_1.ReceiptHttp(nodeUrl);
const transactionHttp = new nem2_sdk_1.TransactionHttp(nodeUrl);
const listener = new nem2_sdk_1.Listener(nodeUrl);
listener.open().then(() => {
    transactionHttp
        .announce(signedTransaction)
        .subscribe(x => console.log(x), err => console.error(err));
  1. Then, retrieve the receipts attached to the block where the receipt was confirmed. The RxJs filters will look for the namespace resolution inside the mosaicResolutionStatements collection.
    listener
        .confirmed(account.address)
        .pipe(
            // Get the block height where the transaction was included
            filter((transaction) => transaction.transactionInfo !== undefined
                && transaction.transactionInfo.hash === signedTransaction.hash),
            // Get the list of receipts triggered for that block
            mergeMap((transaction) => receiptHttp.getBlockReceipts(transaction.transactionInfo!.height.toString())),
            // Iterate over each resolution statement. Find the resolution for the aliased MosaicId.
            map((receipts) => receipts.mosaicResolutionStatements),
            mergeMap((resolutionStatements) => resolutionStatements),
            filter((resolutionStatement) => resolutionStatement.unresolved instanceof NamespaceId
                && resolutionStatement.unresolved.toHex() === aliasedMosaic.id.toHex())
        )
        .subscribe((resolutionStatement:ResolutionStatement) => {
            resolutionStatement.resolutionEntries.map((entry:ResolutionEntry) => {
                console.log("Resolved MosaicId: ", entry.resolved);
                console.log("PrimaryId: ", entry.source.primaryId);
                console.log("SecondaryId: ", entry.source.secondaryId);
            });
            listener.terminate();
        }, err => console.log(err));
});
    listener
        .confirmed(account.address)
        .pipe(
    // Get the block height where the transaction was included
    operators_1.filter((transaction) => transaction.transactionInfo !== undefined
        && transaction.transactionInfo.hash === signedTransaction.hash), 
    // Get the list of receipts triggered for that block
    operators_1.mergeMap((transaction) => receiptHttp.getBlockReceipts(transaction.transactionInfo.height.toString())), 
    // Iterate over each resolution statement. Find the resolution for the aliased MosaicId.
    operators_1.map((receipts) => receipts.mosaicResolutionStatements), operators_1.mergeMap((resolutionStatements) => resolutionStatements), operators_1.filter((resolutionStatement) => resolutionStatement.unresolved instanceof nem2_sdk_1.NamespaceId
        && resolutionStatement.unresolved.toHex() === aliasedMosaic.id.toHex()))
        .subscribe((resolutionStatement) => {
        resolutionStatement.resolutionEntries.map((entry) => {
            console.log("Resolved MosaicId: ", entry.resolved);
            console.log("PrimaryId: ", entry.source.primaryId);
            console.log("SecondaryId: ", entry.source.secondaryId);
        });
        listener.terminate();
    }, err => console.log(err));
});

The previous snippet outputs the resolved mosaic identifier for the namespace cat.currency and the transaction you have just sent.

Resolved MosaicId:  0dc67fbe1cad29e3
PrimaryId:  1
SecondaryId:  0

It is technically possible to get more than one resolutionEntry for the same namespaceId. This situation is common when a namespace owner changes the link to another mosaic, leading to two different resolutions in the same block.

The receipt source primaryId references the transaction where the alias first appears within the block. The secondaryId is a non 0 when the transaction is part of an AggregateTransaction, and it will indicate the index position within the aggregate.

What is next?

Receipts do not only store resolutions for aliases, but also every invisible state change that is not directly retrievable from transactions or the block header. You can check under the receipts documentation the complete list of changes logged.