Getting up to speed with the next major version of MultiChain

MultiChain 2.0 is now under development, and we’ll be releasing alpha versions on this page to let you preview the new functionality. This page will also provide a detailed list of enhancements and other differences between the latest preview / alpha release of MultiChain 2.0 and the latest release of MultiChain 1.0.x. Please note that alpha versions of MultiChain 2.0 should not be used in live production without talking to us first.

Download and Install

The system requirements and installation instructions are the same as for MultiChain 1.0.x, substituting file names as appropriate.

Incompatible API changes

Our general goal is for the MultiChain 2.0 API to be fully backwards compatible with that of MultiChain 1.0.x. Nonetheless, some enhancements cause inevitable changes, and a major release is a good time to deprecate unclear input formats and shorten responses that were too verbose.

Below is a full list of incompatible changes introduced in the MultiChain 2.0 API so far. However if you would like all MultiChain 1.0 fields to remain in the API responses, run MultiChain 2.0 with the runtime parameter v1apicompatible=1.

  • When viewing stream items, key is replaced by keys showing an array of item keys. (If v1apicompatible=1 then key still shows the first key.) Note that when specifying stream items in various APIs, a single key or array can still be used, and key and keys can be used interchangeably.
  • When viewing a wallet transaction, the payload of stream items is not duplicated in the top-level data element.
  • When decoding a raw transaction, empty assets, permissions and items arrays for individual outputs are not shown.
  • When decoding a raw transaction, the payload of raw metadata or stream items is not duplicated in a top-level data element.
  • When using raw transactions to issue an asset, "create":"asset" must be stated in the data element.
  • When using raw transactions to perform a follow-on asset issuance, "update":[asset-identifier] must be stated in the data element.

Protocol versions

To use much of the new functionality in MultiChain 2.0 alpha 2, your chain must be running multichain protocol 20002 or later. This version will be used by default in new chains created using multichain-util that comes with the download.

Existing chains running protocol 10008 or later can also be upgraded, using the create upgrade, listupgrades and approvefrom APIs. This option should be used with caution – MultiChain 1.0.x versions will no longer be able to connect to such an upgraded chain.

Enhanced API commands

The information below should be used together with the MultiChain 1.0.x API documentation.

Affected command(s) Enhancement

All data-hex|object data parameters now support a broader range of raw metadata and stream item types:

  • Raw binary metadata in hexadecimal (as before), e.g. a1b2c3d4
  • Raw textual metadata, e.g. {"text":"hello world"}
  • Raw JSON metadata, e.g. {"json":{"i":[1,2],"j":"yes"}}
  • Binary stream items, e.g. {"for":"stream1","keys":["key1","key2"],"data":"a1b2c3d4"}
  • Textual stream items, e.g. {"for":"stream1","keys":["key1","key2"],"data":{"text":"hello"}}
  • JSON stream items, e.g. {"for":"stream1","keys":["key1"],"data":{"json":{"i":[1,2]}}}

All key parameters now optionally accept an array of keys instead of an individual key. All data-hex parameters now support a broader range of stream item types:

  • Binary data in hexadecimal (as before), e.g. a1b2c3d4
  • Textual data, e.g. {"text":"hello world"}
  • JSON data, e.g. {"json":{"i":[1,2],"j":"yes"}}

To easily publish multiple items to one or more streams in a single transaction, use createrawsendfrom with an array of {"for":"...","keys":[...],"data":...} objects in the data parameter and send in the action parameter.

getstreamitem If the specified transaction contains more than one item for the specified stream, this command will now return an error. See liststreamtxitems for a replacement.
gettxoutdata If the transaction output contains data in text or JSON format, byte ranges are not supported and the response will be formatted as {"text":"..."} or {"json":...} as appropriate.
All create stream and issue APIs now accept any JSON structure for the custom fields parameter, instead of only textual key–value pairs. The JSON will be shown in the response to listassets or liststreams as appropriate.
issue(from) To issue an asset with per-asset send and/or receive permissions, add a restrict field to the params parameter, with one of the values send, receive or send,receive (if both are restricted). For example:
issue <address> '{"name":"asset1","open":true,"restrict":"send,receive"}' 1000 0.01
These APIs can now be used to manage per-asset send and receive permissions using the same syntax as for other per-asset or per-stream permissions. Any address with per-asset admin or activate permissions is able to modify the per-asset send and receive permissions of other addresses for that asset.
Inline metadata can be included inside transaction outputs containing assets. (This is different from regular transaction metadata or stream items which are in a separate output.) Add a "data" key to the object representing asset quantities, whose value is hexadecimal (for raw binary data), or in the form {"text":"..."} or {"json":...} for text and JSON data respectively. For example:
createrawsendfrom <from-addr> '{"<to-addr>":{"asset1":100,"asset2":200,"data":{"json":{"i":[1,2],"j":"yes"}}}}'

When using create upgrade, the following blockchain parameters can now be included: target-block-time maximum-block-size max-std-tx-size max-std-op-returns-count max-std-op-return-size max-std-op-drops-count max-std-element-size. Note that these upgrade parameters can only be applied to chains running multichain protocol 20002 or later. In addition, to prevent abrupt changes in blockchain capacity and performance, the following constraints apply:

  • The target-block-time parameter cannot be changed more than once per 100 blocks.
  • All seven capacity-related parameters cannot be changed to less than half, or more than double, their previous size.

Example: create upgrade upgrade1 false '{"target-block-time":10,"maximum-block-size":16777216}'

New API commands

Command Parameters Description
getstreamkeysummary stream

Outputs a summary of all items in stream (passed as a stream name, ref or creation txid) with stream key key. The mode parameter is a comma-delimited list of keywords. For now, mode must contain jsonobjectmerge, which states that all JSON objects in the qualifying stream items should be merged into a single object. The merged object contains all the JSON keys from the individual objects, with the latest value for each. Optional keywords include:

  • recursive merges JSON sub-objects recursively.
  • noupdate returns the first value for each JSON key instead of the last.
  • omitnull omits JSON keys with null values from the response.
  • ignore ignores non-JSON stream items instead of outputting an error.
  • firstpublishersany only includes items signed by a publisher of the key's first item.
  • firstpublishersall only includes items signed by all publishers of the key's first item.

This API enables a stream to be efficiently used as a general-purpose database, with each stream key representing a separate entity or row.

getstreampublishersummary stream
This works like getstreamkeysummary, except it summarizes all stream items published by address independent of their key, and the firstpublishersany and firstpublishersall keywords are not allowed. This API enables a stream to be efficiently used as an identity database, where each participant independently maintains their own entry.
liststreamtxitems stream
This works like liststreamitems, but listing items in stream within the given txid only. It should be used as a replacement for getstreamitem if multiple items are being published to a single stream in a single transaction.

Internal storage

Within transactions, text data (whether as raw metadata or in stream items) is stored efficiently using UTF-8 encoding. JSON data is stored efficiently using the UBJSON serialization format. More documentation on internal storage formats will be published soon.