Posted by in MultiChain.

Making Smart Filters a whole lot smarter

Today, we’re delighted to release MultiChain 2.1, with two important new features for MultiChain developers.

A year and a half ago, MultiChain 2.0 introduced Smart Filters, which enable custom logic to be embedded in a blockchain for validating transactions and data. Smart Filters are conceptually similar to the “smart contracts” provided by other blockchain platforms, but have a different design to fit MultiChain’s faster transaction model.

Smart Filters come in two varieties – transaction filters and stream filters. A transaction filter validates on-chain transactions in their entirety, by examining their inputs, outputs and metadata. If a transaction doesn’t pass the filter, it is rejected by every node in the network. A stream filter validates individual items written to a MultiChain stream, looking at their key(s), publisher(s) and on-chain or off-chain data, in JSON, text or binary format. If an item doesn’t pass the filter, it is marked as invalid and its data is hidden by every node subscribed to the stream.

Both types of Smart Filter are written in JavaScript and run within a deterministic version of Google’s V8, the super-fast JavaScript engine which powers Chrome, Node.js and many other platforms. Simple filters are easy to code and understand – for example, here’s a stream filter which validates that items have at least two keys:

function filterstreamitem()
    var item=getfilterstreamitem(); // callback function
    if (item.keys.length<2)
        return "At least two keys required";

Overall, we've had great feedback on Smart Filters, but we've also heard repeatedly about two ways we could make them even better. First, many users want filters that can read information which is on the blockchain but not within the transaction or stream item being validated. Use cases include a changing list of permitted countries, exchange rates provided by an external "oracle" or a switch to toggle certain rules.

Second, some developers want to use a set of JavaScript functions in multiple filters, without duplicating code. They also want to be able to update these functions, to fix a bug or cover some new situations, without disabling their existing filters and creating new ones in their place. For example, shared code could contain application-specific logic, a third-party library for validating JSONs or parsing the contents of a PDF.

MultiChain 2.1 introduces two new types of on-chain entity, variables and libraries, to answer these needs.


Let's start with MultiChain variables. These work quite like those in regular programming languages, but with a blockchain twist. Any number of named variables can be created on the blockchain. Each variable has a dynamic set of addresses which is permitted to update its value, and this set is managed by one or more variable administrators (by default, only the variable's creator). Variables are created or updated in a blockchain transaction, which can be sent using a simple high-level API command. Alternatively, lower-level APIs can be used to build complex transactions which atomically set one or more variables, write stream items, transfer assets, change permissions, and so on.

The variable value itself can contain any JSON structure, including numbers, strings, booleans, nested objects and arrays, and is stored on-chain in the efficient UBJSON serialization format. Of course, Smart Filters can query a variable's current value using a simple callback function. But because this is a blockchain, the full history of the variable's values and writers is also available, and can be retrieved in part or in full using another callback function. To make development easier, these callbacks are also available through the application-facing API.


Let's move on to libraries, which are variables' bigger sibling. As with variables, any number of named libraries can be created on the blockchain. But libraries have a richer model for updating, with three available modes – immutable, instant, and subject-to-approval.

Once an immutable library is created, its code can never be changed. A library with instant updates can be changed like a variable, with a set of addresses that can individually replace its code. But in a library with subject-to-approval updates, an update is only applied after being approved by a certain proportion of the blockchain's global administrators. This last mode provides a great trade-off between security and flexibility.

The code for a library is written in regular JavaScript, and defines one or more functions for Smart Filters to use. As with variables, libraries are created or updated in a special transaction, sent easily using the API. When a Smart Filter is created, its required libraries are then provided in an optional parameter. A library always runs in the context of the filter which requires it, so it can use Smart Filter callbacks where appropriate. MultiChain provides extensive functionality for testing (and rolling back) libraries and their updates locally, before making a change on the blockchain.

Wrapping it up

As with all features relating to the blockchain's rules, variables and libraries are available in both the Community and Enterprise editions of MultiChain 2.1. Our developer documentation provides a detailed description of the new JSON-RPC APIs and Smart Filter callbacks available. To use the new features on a blockchain already running, first migrate the nodes to MultiChain 2.1, then upgrade the chain's protocol to version 20012.

So what's next? Over the coming months, we'll be focused on some detailed and intense under-the-hood work, to improve the performance and concurrency of MultiChain while it's under significant load. This will increase the responsiveness of applications which need to query a node while it continues to process hundreds or thousands of new transactions per second.

In the meantime, all of us on the MultiChain team wish our users and customers health and sanity for the year ahead. We know these are difficult times for everyone, and we look forward to returning to the normal rhythm of meetings and conferences as soon as it's safe.


Please post any comments on LinkedIn.