Inline metadata in MultiChain

Including metadata within regular transaction outputs

MultiChain 2.0 adds support for inline metadata, meaning metadata that is included within regular transaction outputs, alongside quantities of issued assets and/or the native blockchain currency. This is different from regular transaction metadata or stream items, both of which appear in separate transaction outputs that do not contain assets and cannot be spent.

A common purpose for inline metadata is to tag some assets with special characteristics, such as transfer restrictions or an expiry date. These types of rules can be enforced using a transaction filter which examines the inline metadata within a transaction’s inputs and outputs during the process of transaction validation. The most useful filter callbacks for this are getfiltertxinput and getfiltertransaction.

To embed inline metadata in a transaction output, use an API command such as send, sendfrom, createrawtransaction or createrawsendfrom which accepts an amounts parameter. This parameter is a JSON object representing a quantity of one or more assets and/or the native blockchain currency. Within the object, include a data key whose value is either a hexadecimal string (for binary inline metadata) or a {"text":"..."} or {"json":...} structure. Some concrete examples can be seen here.

When sending transactions using APIs such as send, sendfrom or createrawsendfrom, outputs containing inline metadata will not be selected for spending unless the lockinlinemetadata runtime parameter is set to false. Outputs containing inline metadata can still be spent explicitly using the createrawtransaction or appendrawtransaction commands (use listunspent to see unspent transaction outputs and their inline metadata).

Inline metadata in transactions

For regular use of MultiChain, you can ignore the technical details below. They are only relevant if you want to work with the raw data within MultiChain transactions. Note that you can also use the raw transactions APIs to encode and decode this information.

Within a transaction output, inline metadata comes after the regular script for the spend condition, and takes the following form:

(item-format OP_DROP) item-data OP_DROP

If the transaction output contains other metadata followed by an OP_DROP, e.g. to represent assets or permissions, the inline metadata can come before or after that other metadata.

The optional item-format has the following structure: (otherwise the data is assumed to be raw binary)

The item-data has the following structure: