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.

Roadmap and references

The following pages describe the enhancements in MultiChain 2.0 released so far:

Protocol versions

To use much of the new functionality in MultiChain 2.0 alpha 5, your chain must be running multichain protocol 20004 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 have their protocol upgraded. This option should be used with caution – earlier MultiChain versions will no longer be able to connect to such an upgraded chain.

MultiChain 2.0 alpha 3+ no longer supports protocols 10007 or earlier, which were used in blockchains created by MultiChain 1.0 alpha 28 and earlier.

New blockchain parameters

Parameter Description Default
admin-consensus-filter Proportion of permitted administrators who must agree to activate or deactivate a transaction filter, between 0 and 1. 0.5
maximum-chunk-size Maximum size in bytes per chunk. (Off-chain stream items are delivered using one or more chunks.) 1048576
maximum-chunk-count Maximum number of chunks in a single off-chain item. 1024
minimum-offchain-fee Minimum transaction fee required to publish off-chain items, in raw integer units of the native currency per 1000 bytes of off-chain data. 0

New runtime parameters

Parameter Description Default
chunkquerytimeout Wait this number of seconds before assuming that a chunk query (to the network as a whole) has failed, returning the chunk back to the queue for later retrying. 25
chunkrequesttimeout Wait this number of seconds before assuming that a chunk retrieval request (to a specific source node) has failed, returning the chunk to the queue for later retrying from a different source. 10
flushsourcechunks Ensure that data for offchain items published by this node is flushed to disk before the transaction referencing them is broadcast. This is important for durability but can incur a performance penalty. 1
maxqueryscanitems The maximum number of transactions to decode for a querying request (currently liststreamqueryitems). 5000
v1apicompatible Include all fields that appeared in MultiChain 1.0.x API responses, even if they have been superceded. Note that only a few incompatible changes have been made from the 1.0 APIs, as explained below. 0

Enhanced API commands

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

Affected command(s) Enhancement
grantwithdata(from)
sendwithdata(from)
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 metadata from the binary cache, e.g. {"cache":"Ev1HQV1aUCY"}
  • Raw textual metadata, e.g. {"text":"hello world"}
  • Raw JSON metadata, e.g. {"json":{"i":[1,2],"j":"yes"}}
  • Binary stream items in hex, e.g. {"for":"stream1","keys":["key1","key2"],"data":"a1b2c3d4"}
  • Binary stream items from cache, e.g. {"for":"stream1","keys":["key1","key2"],"cache":"Ev1HQV1aUCY"}
  • 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]}}}

In addition, all stream items can include an optional "options":"offchain" field to publish their data off-chain.

publish(from) 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
  • Data from the binary cache, e.g. {"cache":"Ev1HQV1aUCY"}
  • Textual data, e.g. {"text":"hello world"}
  • JSON data, e.g. {"json":{"i":[1,2],"j":"yes"}}

A new optional parameter options has been added. Pass a value of offchain to publish as an off-chain stream item.

Command line example: publish stream1 '["key1","key2"]' '{"json":{"name":"Bob"}}' offchain

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. Note that this API can now return an error for off-chain stream items whose payloads have not yet been retrieved from the network.
create(from)
issue(from)
issuemore(from)
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). Command line example:

issue <address> '{"name":"asset1","open":true,"restrict":"send"}' 1000 0.01

grant(from)
grantwithdata(from)
revoke(from)
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.
appendrawtransaction
createrawtransaction
createrawsendfrom
send(from)
sendwithdata(from)
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. Command line examples:

send '{"<to-addr>":{"asset1":100,"data":{"json":[1,2,3]}}}'

createrawsendfrom <from-addr> '{"<to-addr>":{"asset2":20,"data":{"text":"hello"}}}'

create(from)

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 maximum-chunk-size maximum-chunk-count. Note that some of these parameters can only be upgraded in chains running recent protocol versions. 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 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}'

create(from)

When using create stream, the open parameter can now be replaced with an object {"restrict": "..."} that contains zero or more comma-separated terms to describe stream restrictions. Use write to make the stream write-restricted (i.e. not "open" in the previous terminology), offchain to disallow off-chain items in the stream and onchain to disallow on-chain items.

Command line example: create stream stream1 '{"restrict":"write,onchain"}'

unsubscribe A new optional parameter purge has been added, with default value false. When unsubscribing from a stream, pass a value of true to purge off-chain items retrieved for this stream from disk.
pause
resume
The tasks parameter now accepts the value offchain as well as the previous values incoming and mining. A node with offchain paused will not request, relay or deliver off-chain stream items. Note however that if two off-chain items in a stream are identical, the second will be instantly available to subscribers even if off-chain activities are paused.
approvefrom Transaction filters can be approved or unapproved by passing their name, ref or creation txid in the second parameter.

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.
  • ignoreother ignores non-JSON object items instead of giving an error.
  • ignoremissing ignores off-chain items with missing data instead of giving 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.
liststreamqueryitems stream
query
(verbose=false)
This works like liststreamitems, but listing items in stream which match all of the specified keys and/or publishers in query. The query is an object with a key or keys field, and/or a publisher or publishers field. If present, key and publisher should specify a single key or publisher respectively, whereas keys and publishers should specify arrays thereof. Note that, unlike other stream retrieval APIs, liststreamqueryitems cannot rely completely on prior indexing, so the maxqueryscanitems runtime parameter limits how many items will be scanned after using the best index. If more than this is needed, an error will be returned.
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.
createbinarycache This creates a new empty item in the binary cache. The binary cache allows large pieces of data to be prepared for embedding in a chain either as raw metadata or a stream item, while avoiding huge JSON-RPC API requests. Returns a unique textual identifier for the item.
appendbinarycache identifier
data-hex
Appends the hexadecimal data in data-hex to the binary cache item named identifier, and returns its resulting size. Pass the empty string in data-hex to obtain the item's current size. Each binary cache item is stored as a file in the cache subdirectory of the blockchain directory, and can be safely modified on disk directly by external processes.
deletebinarycache identifier Removes the item named identifier from the binary cache.
getchunkqueueinfo Returns information about the queue for retrieving off-chain stream items, providing both a count of chunks and the total number of bytes represented by each state. Chunks can be waiting in the queue, querying across the network, or retrieving from a specific node.
getchunkqueuetotals Returns cumulative statistics on queries and requests for off-chain stream items sent out by this node, and their outcomes. The API provides both a count of chunks and the total number of bytes represented by each outcome. Of the queries sent out to find a chunk in the network, it shows how many were successfully responded and how many were unresponded (no positive response before timeout). Of the requests for delivery sent to specific nodes, it shows how many were successfully delivered, and how many were undelivered (no delivery before timeout) or baddelivered (mismatching data delivered).
getassetinfo asset
(verbose=false)
Returns information about a single asset issued on the blockchain, where asset is the asset name, ref or issuance txid. In assets with multiple issuance events, the top-level issuetxid and details fields refer to the first issuance only – set verbose to true for details about each of the individual issuances. This command can also be used as a Smart Filter callback and so excludes the node-specific information provided by listassets.
getstreaminfo stream
(verbose=false)
Returns information about a single stream created on the blockchain, where stream is the stream name, ref or creation txid. Set verbose to true for the stream's creator addresses. This command can also be used as a Smart Filter callback and so excludes the node-specific information provided by liststreams.
getlastblockinfo (skip=0) Returns information about the last or recent blocks in the active chain. Omit skip or set to 0 for information about the most recent block. Pass 1 for the block before that, and so on. This command can also be used as a Smart Filter callback and provides less information than listblocks or getblock.
verifypermission address
permission
Checks whether the specified address has the specified permission, returning true or false as appropriate. Both global permissions such as connect and per-asset permissions such as stream1.write can be checked. This command can also be used as a Smart Filter callback and provides less information than listpermissions.
testtxfilter restrictions
js-code
(tx-hex)
Tests a transaction filter before it is created on the blockchain. See create txfilter for a description of the restrictions and js-code parameters. If no tx-hex is passed, only compilation is tested, with compiled in the response indicating success, and reason containing the error if compilation failed. If a raw transaction is passed in tx-hex, the transaction is also tested against the compiled filter, with passed in the response indicating whether the transaction passed the filter, and reason containing the reason (given by the filter) if not. The response also contains a log of callbacks made by the filter, including their responses, and the time it took to run.
create(from) type=txfilter
name
restrictions
js-code
Creates a new (as yet unapproved) transaction filter on the blockchain called name. Pass the value "txfilter" in the type parameter (the create API can also be used to create streams and upgrades). To apply the filter for all transactions, pass {} in the restrictions parameter. To only apply for transactions referencing a particular asset or stream, pass {"for":"entity"}, where entity is an asset or stream name, ref or creation txid. To apply for multiple entities, pass {"for":["entity1","entity2",...]}. Pass the JavaScript code for the filter itself in js-code – see Smart Filters for more details. Note that an address requires both admin and create permissions to create a transaction filter. Returns the txid of the transaction creating the filter.
listtxfilters (filters=*)
(verbose=false)
Returns information about transaction filters on the blockchain, whether pending or approved. Pass a filter name, ref or creation txid in filters to retrieve information about one filter only, an array thereof for multiple filters, or * for all transaction filters. The response includes information on whether each filter can be compiled successfully and whether it has been approved by consensus. Set verbose to true to see each filter's creators, which admins have approved it so far, and pending approval changes.
getfiltercode filter Returns the JavaScript code for a filter, where filter is the filter name, ref or creation txid.
runtxfilter filter
(tx-hex)
Tests a transaction filter created on the blockchain, where filter is the filter name, ref or creation txid. If no tx-hex is passed, only compilation is tested, with compiled in the response indicating success, and reason containing the error if compilation failed. If a raw transaction is passed in tx-hex, the transaction is also tested against the compiled filter, with passed in the response indicating whether the transaction passed the filter, and reason containing the reason (given by the filter) if not. The response also contains a log of callbacks made by the filter, including their responses, and the time it took to run.

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 listing streams, or viewing a transaction which created a stream, the open field is superceded by the write field of the restrict subelement (with the boolean opposite value).
  • 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.

Transaction formats

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 the new transaction formats will be published in due course.