Mosaics are fixed assets that represent a set of multiple identical things that do not change.
A mosaic can be what is conventionally called a token, but it can also be a collection of more specialized assets such as reward points, shares of stock, signatures, status flags, votes or other currencies, for example.
Mosaic specialization is achieved through its properties, which are set during mosaic creation.
Once created, each mosaic has a unique identifier represented as a 64-bit unsigned integer. For example, Symbol’s native currency, XYM, has the mosaic ID 0x6BED913FA20223F8.
Note
If you create a mosaic which should be used by other users, it is very convenient to use a Namespace to alias the mosaic ID to a human-readable string. XYM use the symbol.xym alias, for example.
Determines the number of decimal places to which the mosaic can be divided. A divisibility of 3 means that the smallest fraction a mosaic can be divided into is 0.001.
When decimals are used units are called relative, and when no decimals are used units are called absolute. I.e., with a divisibility of 3, 1 absolute unit corresponds to 0.001 relative units. To convert from relative to absolute units multiply by 10divisibility.
Divisibility must be in the 0 to 6 range (included).
Indicates the amount of mosaics initially in circulation, in absolute units.
This amount can be later changed by a MosaicSupplyChangeTransaction if the Supply mutable flag (see below) of the mosaic is set to true.
The total supply must be in the 0 to 9,000,000,000,000,000 range in absolute units.
Specifies the number of confirmed blocks the mosaic is rented for.
Expiring mosaics are allowed to lie in Symbol’s public network up to 3650 days (10 years), being this maximum parameter editable per network.
Non-expiring mosaics can be created by setting this property to 0.
Note
Mosaic duration cannot be extended after its creation. Before creating one, consider if your use case requires the mosaic to expire or not. Note that this behavior is different for Namespaces.
The following formula is used to convert days to blocks approximately:
By default, blockGenerationTargetTimeInSeconds is 30 seconds.
If set to true, the mosaic supply can change at a later point.
In this case, the mosaic creator is allowed to redefine the total mosaic supply with a MosaicSupplyChangeTransaction.
The transaction increases or decreases the mosaic supply in delta units.
To decrease the mosaic supply, the mosaic creator account must own at least delta units.
This means that the mosaic creator cannot remove mosaics from other account balances, even if the supply mutable property is enabled.
If Supply mutable set to false, the mosaic supply cannot be changed. However, if the mosaic creator owns all the mosaic supply, this is modifiable even if the mosaic is defined as not mutable.
If set to true, the mosaic can be transferred between arbitrary accounts. Otherwise, the mosaic can only be transferred to or from the mosaic creator.
If set to true, the mosaic creator can configure custom restrictions.
Mosaics can be revoked (i.e., reclaimed) by the mosaic creator when this flag is set to true.
An account willing to create a mosaic has to pay a rental fee in addition to the transaction fee. Both fees will be deducted from the account’s balance after the announcement of a valid MosaicDefinitionTransaction.
The REST Gateway provides an endpoint to get an estimation of how much network currency will cost you to create a mosaic:
const nodeUrl = 'NODE_URL';
const repositoryHttp = new RepositoryFactoryHttp(nodeUrl);
const networkHttp = repositoryHttp.createNetworkRepository();
networkHttp.getRentalFees().subscribe((rentalFees) => {
console.log(rentalFees.effectiveMosaicRentalFee.compact());
});
const nodeUrl = 'NODE_URL';
const repositoryHttp = new symbol_sdk_1.RepositoryFactoryHttp(nodeUrl);
const networkHttp = repositoryHttp.createNetworkRepository();
networkHttp.getRentalFees().subscribe((rentalFees) => {
console.log(rentalFees.effectiveMosaicRentalFee.compact());
});
By default, creating a mosaic in Symbol’s public network has an initial cost of 0.5 symbol.xym (configurable per network by the mosaicRentalFee property).
However, the network dynamically adjusts the mosaic rental fee over time.
To calculate the effective rental fee, the network multiplies the default value set in the configuration by the network’s dynamic fee multiplier.
