Catapult Elephant Update - (Part 2)

Hi Community, Please find below part 2 of the 3 part series on the latest update to Catapult, Codenamed Elephant! In this instalment, we’ll teach you about Mosaic Restrictions, Metadata, and Account Restrictions. Enjoy!

Spanish: link.
Japanese: link.
Russian: link.
Italian: link.
Mandarin: link.

Part 2 of 3
NEM Catapult Elephant Update
Mosaic Restrictions, Metadata and Account Restrictions

Stomping Elephant (2 of 3):

Mosaic Restrictions, Metadata and Account Restrictions

Catapult is the upcoming full-featured core NEM engine. The development milestones are chronologically alphabetized and code-named for organization and recognition.

The Stomping Elephant series will examine the recent updates in the 5th Catapult milestone, Elephant. In this second part of the series, we will introduce the newly added features - Mosaic Restrictions and Metadata - and the enhancement to Account Restrictions.

Mosaic Restrictions

With the second Elephant update, mosaics have a new configurable property, restrictable. If this property is configured to be true during a mosaic’s creation, the creator will have greater control over the ownership and transference of their asset. The feature will be disabled by default and will not impact tokens where autonomy is desired.

The Mosaic Restriction feature will allow future security tokens issued on the NEM platform to comply with stringent regulations regarding securities. It enables on-chain trading moderation to ensure that only those whose credentials have been officially approved can purchase and trade the securities. Furthermore, Mosaic Restrictions provide a means for authorities to freeze assets if investors breach contractual agreements.

The creator will be able to control the transfer of the mosaic via two mechanisms:

Mosaic Global Restrictions

Global Restrictions can be understood as the network-wide rules of restrictions. Each restrictable mosaic can be attached with one or more of these rules, each stipulating a condition; only the accounts with key identifiers and values that meet the criteria will be given permission to execute transactions involving the asset.

Mosaic Address Restrictions

Mosaic Address Restrictions determine the status of each individual account in regards to the restrictable mosaic. They are designated and modified by the mosaic creator using the Mosaic Restriction Transactions, and they determine whether the account will be able to transact the mosaic.

If the status of an account fulfills the values set in the Global Restrictions, the account will be able to transact with the mosaic. Otherwise, the account will need to request the mosaic creator to be granted elevated permissions or wait until the Mosaic Global Restrictions are altered.


Let’s say a company, CharlieChocolateFactory, wants to go public by tokenizing their shares and conducting an STO. They create a mosaic “CCF.Shares” and configure it to be restrictable.

To comply with regulations, the company wants only the participants that have passed the KYC/AML process to buy and transact their stock. So the company creates a Global Restriction that permits only accounts with elevated statuses to interact with the asset. The Global Restriction is set as “CCF.Shares, KYC, EQ = 1”, which can be read as “only allow accounts to transact with the CCF.Shares mosaic if their “KYC” restriction key for it has a value equal to 1.

When investors complete the KYC/AML process the CharlieChocolateFactory alters their accounts with a Mosaic Address Restriction transaction with parameters “CCF.Shares, KYC, 1”, allowing certified investors to participate in the STO. Others who have not provided the necessary information will not be able to receive or trade the asset as their accounts will not meet the requirements of the Global Restriction.

Additionally, mosaic creators will be able to define restrictions that depend directly on Global Restrictions set on separate mosaic - known as the reference mosaic. The referenced mosaic and the restricted mosaic do not necessarily have to be created by the same account, enabling the delegation of mosaic permissions to a third party.

For more information or technical details on how to use Mosaic Restrictions, please visit the NEM Developer Center.


The Elephant update will also bring an option to associate metadata with objects, allowing users to attach relevant information to accounts, mosaics, and namespaces.

The metadata will be assigned using Metadata Transactions. These transactions can be initiated by 3rd parties but will not be executed without the account owner’s explicit permission.

Similarly to transfer transaction messages, the metadata values are be free form and will not need to be validated by the blockchain. Catapult stores the history of metadata assignments in the blockchain, keeping the latest value assigned to an object in the state for rapid indexing.


Metadata will be a unique feature with a variety of use-cases because it will allow users to not only attach vital information to objects but also perform off-chain action contingent on specific values contained by it.

Here are some examples of how businesses or users could take advantage of this feature:

  1. Digital notarization – Important documents, such as certifications, affidavits, and agreements could be attached to accounts as proof of authenticity on the blockchain. A trusted party can verify the documents and sign the metadata onto accounts, digitizing the validity of the documents for convenience and security.

  2. Access Management – Entities could use metadata to regulate access to its sensitive resources. Each account could be tagged with metadata with specific conditions (clearance level, when, where, etc) for valid access. When access is requested, an app would perform checks to ensure the conditions are matched before granting it.

  3. Security Token Identifier – Metadata can be used to attach information about security tokens. Small pieces of data, such as legal name, ticker, or ISIN, can be attached as on-chain metadata, while sizable documents, like the prospectus or investor agreement, can be kept off-chain.

  4. Public Namespace Verification - Metadata could be attached to namespaces to help users verify domain ownership. The contained data could include information such as registrant, administrative, or technical contact information. This would solidify the trust users have of namespaces on blockchain as it gives them a way to double-check associations before interaction.

To learn more about how to use Metadata, please visit the NEM Developer Center.

Account Restrictions

Outgoing Account Restrictions

First introduced in the Cow milestone, Account Restrictions allow users to set “smart rules” that filter unwanted incoming transactions by address, transaction type, or mosaic. These “smart rules” are editable and unique to each account.

Note: You might remember this feature as “Account Filters” or “Account Properties” but it has been renamed as “Account Restrictions” for naming congruence with Mosaic Restrictions.

With the Elephant update, Account Restrictions will be able to filter outgoing transactions (by address and operation) in addition to incoming ones. This means that users can implement restrictions on sending as well as receiving transactions. The improvement will increase the adjustability of NEM accounts and function mainly as a safety feature.


One of Barry’s NEM accounts becomes compromised when he misplaces his diary with his private keys written inside it. To prevent himself from accidentally sending assets to the lost account, Barry applies Account Restrictions to his other accounts and adds his lost account as a blocked recipient. If Barry accidentally attempts to send assets to his lost account, the outgoing transaction would be blocked and his assets would remain safe.

Dale is using one of her NEM accounts as a savings account. She knows that she has no plans to spend the assets in that account anytime in the near future. Thus, she disables outgoing transfer transactions using Account Restrictions. Dale feels safer knowing that any unintended transactions including the mosaic would be denied.

Preview of Part 3

In the last part of the series, we will look at the remaining updates in Elephant. It will examine delegation unlocking, support for dynamic rental fees, and other minor updates. Stay tuned to learn about the new developments!

If you missed the first part of the series, you can catch up about Catapult’s new consensus algorithm PoS+ here.