Migrating from NEM to Symbol

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


This guide is a living document. The information could change as Symbol development advances.

Comparison between NIS1 and Symbol
NEM NIS1 Symbol
Built-in features  
Mosaics Mosaics
Namespaces Namespaces
Delegated Harvesting Delegated Harvesting
Multisig Accounts Multi-level Multisig Accounts
Mosaic Restrictions Advanced Mosaic Restrictions
Account Restrictions
Metadata Controls
Aggregated Transactions
Cross-Chain Swaps
Coded in Java Coded in C++
POI (Proof of Importance) POS+ (Proof of Stake Plus)
Keccak-SHA3-512 SHA-512
Fixed Fees Dynamic Fees
Merkle Proofs

Test network

At the time of writing, the main public network has not been launched. Right now, there are two options to start testing Symbol.

  • Public test network The public test network uses the same technology and features of the future main public network. You can use the testnet to experiment with the offered transaction set in a live network without the loss of valuable assets. To start using the test net, follow this guide.
  • Private test network: To run a private test network, use the package catapult-service-bootstrap. This software suite contains the necessary setup scripts to build a network for development and learning purposes with just one command.

Legacy API incompatibility

Legacy API calls that used to work for NIS1 network nodes are not compatible with Symbol. Now, 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 Symbol 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 by NEM Library from NIS1.

See also:

Accounts management

Both platforms use the digital signature algorithm named Ed25519, but with different hashing algorithms. While NIS1 uses Keccak-SHA3-512, Symbol changed to SHA-512 to support TLS.

The change in the hashing algorithm used leads to have, for the same private key in NIS1 and Symbol, different public keys, and addresses.

See also:

Legacy transactions

NIS1 transactions serialization format is not compatible with Symbol. Yet, most of the transaction types have only evolved and none have been removed. This implies a possible upgrade to Symbol 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. Symbol receives the response of the call asynchronously, eliminating blocking calls.

Additionally, Symbol only has one version of TransferTransaction. The native currency is now pushed as a regular mosaic in the mosaics array of the transaction.

See also:

Transaction fees

Symbol transaction fees are dynamic and decided by the network participants. Each transaction effective fee is calculated by multiplying a fee multiplier by the transaction size. The fee multiplier is attached in the block where the transaction gets confirmed, and it is defined by the node owner harvesting the block.

During the transaction definition, the sender limits the maximum fee authorized to include the transaction in a block.

See also:


Notable changes have happened at protocol level with regards to mosaics management as they are now independent of namespaces.

In fact, NIS1 namespaces expire altogether with assets linked to them. Symbol mosaics are configured to have their own duration, as well as being assigned a unique nonce value.

Lastly, levies are not available on Symbol.

See also:


Namespaces can still refer to mosaics using AliasTransactions. 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, Symbol 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 creator 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 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.

See also:

Multisignature management

With multisignature accounts managed on-chain, Symbol’s multisignature implementation is different from many other—so-called client-side—multisignature implementations.

  1. Creating 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 MultisigAccountModificationTransaction must be wrapped in an AggregateTransaction.

  1. Multi-Signature transactions work with aggregate transactions.

The new AggregateTransaction 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.

See also:

Need help?

After reading this documentation, you might still have some unanswered questions.

In this site, you will find descriptions for every new feature and self-paced guides on how to use the software development kits.

We invite you to connect connect with our developer community by joining the Slack.