Migrating from NIS1 to Catapult

With Catapult, most of the previously available NIS1 features have evolved. This document will help you upgrade your application previous NIS1 features, to the newly available Catapult technology.

Note

This guide is a live document. The information could change as Catapult development advances.

Test network

The package catapult-service-bootstrap brings a set of scripts to deploy a complete Catapult test network for development and learning purposes.

Note

⚠️Catapult software and the service bootstrap scripts are still under development. Do not power any network in production using these packages.

Legacy API incompatibility

Legacy API calls that used to work for NIS1 network nodes are not compatible with Catapult. With Catapult, API requests mostly happen with REST API nodes, usually on port 3000.

There are several Software Development Kits that have been - and some that are - under development for Catapult distributed ledgers consumer applications. As of now, the planned SDKs to be supported are written in: Typescript / Javascript / NodeJS, Java, C#, Go, Python and Swift.

As a starting point, we suggest reviewing the TS/JS SDK as it is the most used SDK and leads in documentation. The architecture of the TS SDK is inspired in NEM Library from NIS1.

Accounts management

Management of account with Catapult has not changed much compared to the previous NIS1 public network accounts. A few notable changes have happened as to public verifiability of accounts and field names returned in the REST endpoints.

Legacy transactions

NIS1 transactions serialization format is not compatible with Catapult. Yet, most of the transaction types have only evolved and none have been removed. This implies a possible upgrade to Catapult transactions that involve fewer changes.

The first notable change about transactions is that the status response is received through WebSocket channels. In NIS1, the client received the response of the API call right after announcing a transaction. Catapult receives the response of the call asynchronously, eliminating blocking calls.

Additionally, there is only one transfer transaction version remaining in which mosaics are always pushed in the mosaics array, when available. This is different from NIS1 transfer transactions which, in their first version, attached XEM without using the mosaics array.

Transaction fees

The fee that needs to be paid for a transaction now depends on the transaction size and node owners can specify a positive (or zero) fee multiplier. The effective fee paid for a transaction can be calculated reading the fee multiplier from the block in which the transaction got confirmed and multiplying it by the size of the transaction.

Transactions fees are specified with the maxFee field. This field represents the maximum fee allowed to be paid for this transaction to confirm.

Mosaics & namespaces

Notable changes have happened at protocol level with regards to mosaics management as they are now independent of namespaces. In fact, in NIS1, it happened that namespaces would expire altogether with assets linked to them.

With Catapult, mosaics are configured to have their own duration instead, as well as being assigned a unique nonce value.

Lastly, levies are not available on Catapult, those must be reproduced with aggregate transactions instead.

Namespaces can still refer to mosaics byways of alias transactions. A namespace owner can attach either of an account or a mosaic id to one of its’ namespaces. The namespace information endpoint will return the linked object in the alias field.

Also, root namespaces have a duration field that is expressed in a count of blocks which means yearly renewal is not mandatory anymore.

In order to facilitate the transfer of mosaics, a mosaic owner should register a namespace and alias the mosaic with that namespace. End-users can send transactions using the alias to refer to the mosaic.

When a transaction includes an alias, a so-called resolution reflects the resolved value of that alias in the block. To get the real identifier behind an aliased address or mosaic, the client application needs to fetch the related resolution receipt linked to the block where the transaction gets included.

Multisignature management

With multisignature accounts managed on-chain, the NEM multisignature implementation is different from many other - so-called client-side - multisignature implementations.

  1. An account must be converted to a multisignature account.

Different to NIS1, the account modification entries now hold fields for minimum approval and minimum removal:

Minimum removal: Defines how many cosignatories are required to broadcast transactions removing cosignatories from the multisignature account.

Minimum approval: Defines how many cosignatories are required for any other type of transaction.

Additionally, cosignatories that are added to multisignature accounts now have to confirm the modification by sending a cosignature (opt-in process). In order to facilitate this process, transactions with type ModifyMultisigAccount must be wrapped in an aggregate transaction.

  1. Multi-Signature transactions work with aggregate transactions.

The new aggregate transaction permits to wrap multiple transactions together involving different participants. If all the participants cosign the aggregate, the inner transactions are included atomically in the block. Otherwise, none of the transactions will get confirmed.

To send a multisig transaction as in NIS1, the initiator of the transaction has to add it as an inner transaction of the aggregate. Then, the minimum number of cosignatories defined in the multisignature will have to cosign the aggregate to allow announcing transactions from the shared account.

Need help?

While migrating from NIS1 to Catapult, you might still have some unanswered questions. In the NEM Developer Center, you can find more new features described along with step-by-step integration guides.

You can also ask integration related questions on StackOverflow, or reach our community of developers joining the official Slack.