Migrating from NIS1 to Symbol

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


You can move your NIS1 assets to a Symbol account by Opting-in. For more information, see Retrieving your XYM from a post-launch opt-in.

Feature comparison between NIS1 and Symbol



Built-in features





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)



Fixed Fees

Dynamic Fees


Merkle Proofs

Test network

Right now, there are two options to start testing Symbol which do not involve spending funds.

  • Public test network The public test network uses the same technology and features of the 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 Symbol Bootstrap. This tool 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 MosaicAliasTransaction. 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 Aggregate Transaction.

  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:

Last updated by Xavi Artigas on 2021-10-06.

Did you find what you were looking for? Give us your feedback.