RestrictionsβοΈ
- Restriction
- An advanced feature, also referred to as a rule, that allows fine-grained control over how specific accounts or mosaics can be used.
If a transaction violates any active restriction, it is rejected during validation and never confirmed. All restrictions are stored on-chain and validated by all network nodes.
They are also enforced within aggregate transactions. If any embedded transaction violates the applicable rules, the entire aggregate transaction is rejected.
Restrictions are created and managed using specialized restriction transactions, and are stored on-chain and therefore publicly visible. This allows external systems to evaluate eligibility or compliance without needing to trust off-chain logic.
There are two main types of restrictions:
Info
Originally designed for specialized use cases requiring strict controls, such as compliance requirements or internal policy enforcement, restrictions have also been adopted for other purposes, including enhancing security and limiting spam.
Account-Based RestrictionsβοΈ
- Account Restriction
- A type of restriction that limits what an individual account can do, such as which addresses it can interact with, which mosaics it can receive, or what transaction types it can initiate.
Account restrictions can only be created, modified, or removed by the account itself. If the account is part of a multisignature account, any changes must be approved by the required number of cosigners.
Account Address RestrictionsβοΈ
- Account address restriction
- A type of account restriction that controls which other addresses a given account is allowed to interact with.
This restriction allows either blocking (blocklisting) or allowing (allowlisting) specific addresses, but not both modes simultaneously.
The restriction can be applied to incoming transactions, outgoing transactions, or both.
Examples
An account can be configured to:
-
Reject any transactions sent to blocklisted addresses.
- Set an outgoing address restriction in blocklist mode, and include the unwanted addresses.
-
Ignore any transactions from unapproved sources.
- Set an incoming address restriction in allowlist mode, and list only the trusted source accounts.
-
Allow interactions only with a predefined set of trusted accounts. This is useful, for example, when an account is restricted to internal use within an organization.
- Set both incoming and outgoing address restrictions in allowlist mode, using the same list of approved accounts.
Account Mosaic RestrictionsβοΈ
- Account mosaic restriction
- A type of account restriction that limits which mosaics an account is allowed to receive.
This restriction supports either blocking (blocklisting) or allowing (allowlisting) incoming transactions containing specific mosaics (but not both modes simultaneously).
Outgoing transactions are not affected. There is no equivalent restriction for mosaics sent from the account.
If an incoming transaction contains multiple mosaics and any of them violate this restriction, the entire transaction is rejected.
Note that this restriction applies to any transaction type that results in mosaics being transferred to the account, not just to transfer transactions.
Examples
An account can be configured to:
-
Block the reception of certain unwanted mosaics, for example, those used by spammers.
- Set an account mosaic restriction in blocklist mode and list the mosaics to block.
-
Allow only a specific set of approved mosaics. This is useful, for example, when an account's contents are publicly visible and should remain uncluttered by unsolicited or irrelevant tokens.
- Set an account mosaic restriction in allowlist mode and include only the allowed mosaics.
Account Operation RestrictionsβοΈ
- Account operation restriction
- A type of account restriction that limits which types of transactions an account is allowed to initiate.
This restriction supports either blocking (blocklisting) or allowing (allowlisting) the transaction types that an account is allowed to perform (but not both modes simultaneously).
Note
Attempts to disallow the ACCOUNT_OPERATION_RESTRICTION transaction type are rejected by the protocol.
This prevents accounts from accidentally locking themselves into an overly restrictive set of allowed operations.
The restriction can be used to prevent accidental use of the wrong account, but it does not prevent the account owner from lifting the restriction (except in the case detailed in the warning box above).
All transaction types can be restricted. See the list of supported types in the Transactions page.
Examples
-
Limit an account to namespace registration and renewal only.
- Set an account operation restriction in allowlist mode that allows only namespace-related and restriction-related functions.
-
Do not allow moving funds from an account.
- Set an account operation restriction in blocklist mode that forbids transfer transactions.
Mosaic-Based RestrictionsβοΈ
- Mosaic Restriction
- A type of restriction that defines rules accounts must satisfy in order to transact with a given mosaic.
Unlike account restrictions, which limit what a specific account can do, mosaic restrictions impose rules from the mosaic's perspective. Any account wishing to use the mosaic must comply with them.
These restrictions are created and managed by the mosaic creator. Other accounts cannot set or modify restrictions on mosaics they do not own.
The restrictions apply to the mosaic creator too, which must be explicitly authorized like every other account.
Note
Restrictions can only be applied to mosaics that have been created with the Restrictable flag.
To apply a restriction to a mosaic, two components must be defined, one on the mosaic, and one on each account wishing to use the mosaic:
- A mosaic global restriction, which specifies a condition that accounts must meet in order to interact with the mosaic.
- A mosaic address restriction, which assigns a value to an account that will be compared against the condition.
This dependency is unique to mosaic restrictions. Account restrictions, by contrast, do not require multiple parts to work.
Mosaic Global RestrictionsβοΈ
- Mosaic Global Restriction
- One of the two components required to apply a mosaic restriction. It defines a rule that all accounts must satisfy in order to interact with a mosaic.
These restrictions are expressed as keyβvalue conditions, set by the mosaic creator. Each condition includes:
-
A mosaic ID: identifies the mosaic being restricted. Only its owner can restrict it.
-
A restriction key: an arbitrary number defined by the creator that identifies this particular restriction.
This is necessary because a mosaic may define multiple restrictions. Keys are independent for each mosaic.
The key is a number, but it can be derived from a more memorable string (e.g.
KYC) using a hash function. -
A restriction value: the threshold against which each account's value will be compared.
-
A comparison operator: defines how each account's value is compared to the threshold (e.g. equal, not equal, greater than).
Example
A mosaic that requires each account to have a value of 1 for the key KYC can use the following
configuration:
| Field | Value |
|---|---|
| mosaic ID | Mosaic being restricted. |
| Key | Hash of KYC |
| Value | 1 |
| Operator | Equal |
Once a global rule is set, the mosaic owner must explicitly assign values to accounts using Mosaic address restrictions (see next section), which are then evaluated against the global condition.
Additionally, a mosaic global restriction can depend on the restriction values of another mosaic, known as the reference mosaic. See the Reference Mosaics section below for details.
Mosaic Address RestrictionsβοΈ
- Mosaic Address Restriction
- One of the two components required to apply a mosaic restriction. It assigns restriction attributes to a specific account, which are then evaluated against the condition defined in the corresponding mosaic global restriction.
These attributes are set by the mosaic creator and act as account-specific metadata. An account is allowed to transact with a mosaic if all the global restrictions for the mosaic are satisfied by the restriction attributes set on the account.
To configure a mosaic address restriction, the following attributes must be provided:
- A mosaic ID: identifies the mosaic being restricted. Only its owner can issue this restriction.
- A Target account: the address the restriction applies to.
- A Restriction key: selects an active global restriction.
- A Restriction value: a value to assign to the account, which will be compared to the value in the selected global restriction, according to the comparison operator.
Example
Continuing the example from the previous section, to allow an account to transact with the restricted mosaic, the mosaic creator needs to submit the following mosaic address restriction:
| Field | Value |
|---|---|
| mosaic ID | Restricted mosaic. |
| Target Account | TABC123... |
| Key | Hash of KYC |
| Value | 1 |
The mosaic global restriction with the key KYC will be selected, and its value 1 compared for equality with
the value 1 in the mosaic address restriction.
Since the values are equal, the account TABC123... is allowed to transact with this mosaic.
Reference MosaicsβοΈ
A mosaic global restriction can specify a reference mosaic, which provides the mosaic address restrictions used by the derived mosaic. The two mosaics do not need to belong to the same account and can, in fact, be managed by independent organizations.
This allows, for example, one company to create a certification mosaic and perform a certification process on individual accounts by assigning address restriction values to them.
Another company can then create its own derived mosaic, reference the certification mosaic, and define any mosaic global restrictions it wishes. The certification values assigned to accounts by the reference mosaic are then evaluated against the global restrictions defined by the derived mosaic.
Note that only the mosaic address restrictions of the reference mosaic are reused by the derived mosaic. The mosaic global restriction rules defined on the reference mosaic apply only when transacting with the reference mosaic itself.
When transacting with the derived mosaic, only the global restrictions defined by the derived mosaic are evaluated against the address restriction values provided by the reference mosaic.
Example
Suppose a company creates a certification mosaic with a certification_level restriction ranging from 1 to 5.
The company then certifies several accounts by assigning them address restriction values:
| Account | Certification level |
|---|---|
| Account A | 5 |
| Account B | 2 |
| Account C | No certification |
Another organization can then create derived mosaics that reference this certification mosaic.
For example:
| Derived Mosaic | Global Restriction |
|---|---|
PREMIUM_ASSET |
certification_level >= 4 |
BASIC_ASSET |
certification_level >= 2 |
The resulting access permissions are:
| Account | PREMIUM_ASSET |
BASIC_ASSET |
|---|---|---|
| Account A | β Allowed | β Allowed |
| Account B | β Rejected | β Allowed |
| Account C | β Rejected | β Rejected |
In this example, the same certification mosaic is reused by multiple independent mosaics, each defining its own access requirements. Accounts with higher certification levels can interact with a wider range of mosaics, while uncertified accounts are rejected automatically by the restriction rules.
SummaryβοΈ
The following table summarizes the main numerical limits related to restrictions.
| Limit | Value |
|---|---|
| Maximum number of restrictions per account | 100 |
| Maximum number of restrictions per mosaic | 20 |
The following table summarizes all the available restriction operators:
| Operator | Meaning |
|---|---|
NONE |
No restriction |
EQ |
Allow if equal |
NE |
Allow if not equal |
LT |
Allow if less than |
LE |
Allow if less than or equal |
GT |
Allow if greater than |
GE |
Allow if greater than or equal |