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 1, your chain must be running multichain protocol 20001 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.

Command Description
grantwithdata
grantwithdatafrom
sendwithdata
sendwithdatafrom
completerawexchange
appendrawdata
appendrawtransaction
createrawtransaction
createrawsendfrom

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]}}}
create
createfrom
issue
issuefrom
issuemore
issuemorefrom
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.
publish
publishfrom

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.

New API commands

Command Parameters Description
getstreamkeysummary stream
key
mode

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
address
mode
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
txid
(verbose=false)
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.