Metadata

Symbol provides you with an option to associate metadata to an account, mosaic or namespace with a transaction.

The most common uses of metadata are:

  • Attach relevant information to your assets.
  • Validate the value attached to an asset to enable users in your application to perform an off-chain action.

Metadata is uniquely identified by the tuple { signer, target-id, metadata-key }. Including a signer in this composite identifier allows multiple accounts to specify the same metadata without conflict.

The value linked to an identifier is a string up to 1024 characters, being this parameter editable per network. The client application is responsible for encrypting the message or keeping it visible for every blockchain participant.

Persistence

Metadata entries are stored on the blockchain—like the message of a regular TransferTransaction—but also as a key-value state.

This feature reduces the reading time of client applications; metadata allows information to be accessed by keys instead of processing the entire account transaction history off-chain to obtain the latest transaction message value.

Permissions

The account, namespace or mosaic creator must opt-in to all metadata requests received by giving explicit permission. In practice, this means that all MetadataTransactions must be wrapped in an AggregateTransaction.

The target account should cosign the aggregate to record the metadata on the blockchain and update the asset state.

Examples

Adding a certificate to an account

../_images/metadata-certificate.png

Metadata used to attach relevant information to an asset

Bob works as a digital notary that stamp accounts on Symbol’s public blockchain. When a customer comes to Bob to notarize a document, he checks the authentication of the customer’s documents then tags the account with a MetadataTransaction.

Alice a recent graduate and wants her educational certificate accredited to her Symbol account to avoid the hassle of repeatedly providing verification of her degree. So she goes to Bob and provides him with proof of her degree. Once Alice pays Bob a fee, Bob verifies the authenticity and stamps Alice’s account with metadata that signifies her degree.

Access management

../_images/metadata-access-control.png

Validating metadata to restrict performing an off-chain action

The HR department of the SneakersCompany uses the Symbol for access management of sensitive work resources. Each account is tagged with the metadata that regulates its access to the company apps suite.

When a new employee, Carol, is hired, the HR department creates a new work account for her. For security reasons, HR sets the metadata of the account to {company, ACCESS, 9-18}.

Each time Carol attempts to access the company apps suite, the company app validates that Carol has permission and that the time falls under 9:00-18:00 before granting her admission.

On the other hand, if Derek, who has no permissions, attempts to access the company apps suite, the company app will reject his request.

Guides

Continue: Transfer Transaction.