Old formats for native assets and data streams metadata
Version 1.0 alpha 27 of MultiChain introduced a new MultiChain protocol version, which makes a number of changes to how native asset and data stream operations are represented in blockchain transactions. This applies both to “inline metadata” in standard outputs (using an OP_DROP opcode), and metadata stored in an output of its own (using an OP_RETURN opcode). The format of permissions transactions was not changed.
New versions of MultiChain still support blockchains which use earlier protocols. However, by default, chains created in 1.0 alpha 27 or later will use the new protocol 10007, which is not compatible with earlier versions of MultiChain. A blockchain’s protocol and version can be seen in the protocol and protocolversion fields of the response to getinfo. New blockchains can be explicitly started with an old protocol by setting the appropriate blockchain parameter, as described here.
The main documentation on the MultiChain site now describes protocol version 10007 or later, with differences in previous versions documented below. The most important change is that new protocols specify an asset in OP_DROP metadata using a 16-byte prefix of the txid of that asset’s issuance transaction, instead of the issuance’s block number and byte offset. This resolves two problems: (a) assets could not be transferred before their issuance was confirmed in the blockchain, and (b) in very rare cases, a blockchain reorganization could lead to asset transactions being rendered invalid. In addition, there are changes to how asset and stream details are represented in OP_RETURN outputs, and the new protocol allows an asset to be created or updated in a transaction without specifying a quantity of that asset in one of the transaction’s non-OP_RETURN outputs.
Asset new issue metadata (protocol versions up to 10006)
A transaction issues a new asset if the following metadata is encoded at the end of one or more output scripts, followed by an OP_DROP (0x75):
| Field | Size | Description |
| Identifier | 4 bytes | spkg or 0x73 0x70 0x6b 0x67 |
| Raw quantity | 8 bytes | Number of raw integer transaction units created, unsigned 64-bit integer in small-endian order. |
If multiple outputs of a single transaction contain this type of metadata, a single asset will be created, and each output will receive the quantity of that asset specified within its metadata.
In a transaction which creates an asset, more information can be given about the asset in a separate OP_RETURN output containing the following:
| Field | Size | Description |
| Identifier | 4 bytes | SPKa or 0x53 0x50 0x4b 0x61 |
| Quantity multiple | 4 bytes | Multiply the asset quantity in display units by this number in order to calculate raw units. Display units are used for MultiChain API calls, whereas raw units are used within transaction OP_DROPs. Stored as an unsigned 32-bit integer in small-endian order, e.g.: 0x64 0x00 0x00 0x00 = 100 for an asset where 1 raw unit = 0.01 display units. |
| Asset name | Variable | Null-delimited name of asset, e.g. 0x61 0x73 0x73 0x65 0x74 0x31 0x00 for asset1. |
| Repeat the below for each additional asset property | ||
| Property key | Variable | If the first byte of the key is 0x00, it denotes a property with special meaning to MultiChain, and the second byte gives the property type. For now, the only possible key is 0x00 0x02, where a property value of 0x00 or 0x01 denotes whether the asset is open for reissuance. If the first byte of the property key is not 0x00, it contains the null-delimited name of a user-defined custom field, e.g. 0x75 0x72 0x6c 0x00 for url. |
| Length | 1-9 bytes | Bitcoin-style variable-length integer indicating the length of the property value in bytes. |
| Value | Variable | The property’s value as raw binary. |
If this OP_RETURN metadata is not present, the asset is not open for reissuance, has a quantity multiple of 1 and no name, but can still be referred to using its asset ref or issuance txid.
Per-output asset metadata (protocol versions up to 10006)
The presence of assets in an output (excluding the transaction which created those units) is represented by the following metadata at the end of its script, followed by an OP_DROP:
| Field | Size | Description |
| Identifier | 4 bytes | spkq or 0x73 0x70 0x6b 0x71 |
| Repeat the below for each asset | ||
| Issue block | 4 bytes | Block number in which the asset’s first issuance transaction was confirmed, unsigned 32-bit integer in small-endian order. |
| Issue offset | 4 bytes | Byte offset of the asset’s first issuance transaction within that block, unsigned 32-bit integer in small-endian order. |
| Issue txid prefix | 2 bytes | First two bytes of the txid of the asset’s first issuance transaction. |
| Raw quantity | 8 bytes | Number of raw integer asset units, unsigned 64-bit integer in small-endian order. |
Note that assets are tagged using their asset reference, rather than the transaction ID of their issuance. This means that assets can only be transferred for the first time after their issuance transaction has been confirmed.
Asset follow-on issue metadata (protocol versions up to 10006)
A transaction issues additional units of an existing asset if the following metadata is encoded at the end of one or more output scripts, followed by an OP_DROP (0x75):
| Field | Size | Description |
| Identifier | 4 bytes | spko or 0x73 0x70 0x6b 0x6f |
| First issue block | 4 bytes | Block number in which the asset’s first issuance transaction was confirmed, unsigned 32-bit integer in small-endian order. |
| First issue offset | 4 bytes | Byte offset of the asset’s first issuance transaction within that block, unsigned 32-bit integer in small-endian order. |
| First issue txid prefix | 2 bytes | First two bytes of the txid of the asset’s first issuance transaction. |
| Raw quantity | 8 bytes | Number of raw integer asset units, unsigned 64-bit integer in small-endian order. |
If multiple outputs of a single transaction contain this type of metadata, a single follow-on issuance event will take place, with each output receiving the quantity of that asset specified within its metadata.
In a transaction which performs a follow-on issuance, more information can be given about the issuance in a separate OP_RETURN output containing the following:
| Field | Size | Description |
| Identifier | 4 bytes | SPKc or 0x53 0x50 0x4b 0x63 |
| Repeat the below for each asset property | ||
| Property key | Variable | If the first byte of the key is 0x00, it denotes a property with special meaning to MultiChain, and the second byte gives the property type. If the first byte of the property key is not 0x00, it contains the null-delimited name of a user-defined custom field, e.g. 0x75 0x72 0x6c 0x00 for url. |
| Length | 1-9 bytes | Bitcoin-style variable-length integer indicating the length of the property value in bytes. |
| Value | Variable | The property’s value as raw binary. |
Note that it is not possible to mix issuances (whether original or follow-on) of more than one asset type in a single transaction. However it is possible to combine one new asset issuance with regular transfers of pre-existing assets.
Stream creation outputs (protocol versions up to 10006)
A transaction output creates a stream if it contains the following, followed by an OP_DROP:
| Field | Size | Description |
| Identifier | 4 bytes | spkn or 0x73 0x70 0x6b 0x6e |
| Entity type | 1 byte | 0x02 for a stream. |
In the output that creates a stream, more information can be given about that stream in an OP_RETURN payload containing the following:
| Field | Size | Description |
| Identifier | 4 bytes | SPKc or 0x53 0x50 0x4b 0x63 |
| Repeat the below for each stream property | ||
| Property key | Variable | If the first byte of the key is 0x00, it denotes a property with special meaning to MultiChain, and the second byte gives the property type. For now, the only possible keys are 0x00 0x01, for the stream’s name, and 0x00 0x04, where a property value of 0x00 or 0x01 denotes whether the stream is open to all writers. If the first byte of the property key is not 0x00, it contains the null-delimited name of a user-defined custom field, e.g. 0x75 0x72 0x6c 0x00 for url. |
| Length | 1-9 bytes | Bitcoin-style variable-length integer indicating the length of the property value in bytes. |
| Value | Variable | The property’s value as raw binary. |
Stream item outputs (protocol versions up to 10006)
A transaction output contains a stream item if it has exactly the following structure:
stream-identifier OP_DROP item-key OP_DROP OP_RETURN item-data
The stream-identifier has the following structure:
| Field | Size | Description |
| Prefix | 4 bytes | spke or 0x73 0x70 0x6b 0x65 |
| Stream | 16 bytes | First 16 bytes of stream creation txid in reverse order. |
The item-key has the following structure:
| Field | Size | Description |
| Prefix | 4 bytes | spkk or 0x73 0x70 0x6b 0x6b |
| Key data | Variable | Binary data of item key (can be empty). |
The item-data has no prefix and is embedded directly after the OP_RETURN.