Migrating from Nxt to Ardor

Introduction

Migrating an existing application which relies on the NXT APIs to Ardor is a relatively simple task.

This page outlines the API differences between the platforms and explains how to convert the NXT APIs to the Ardor APIs.

Adapting your Applications to the Parent/Child Chain Design

In Ardor, APIs which submit or query chain specific data has to specify the "chain" parameter.

The value the "chain" parameter can be set to the unique chain name or the numeric chain id.

The chain name for the parent chain is ARDR and its id is 1

The chain name for the first child chain is IGNIS and its id is 2

These values are unlikely to change in the future so can be hard coded in your application for simplicity.

To read a list of all existing chains use the getConstants API which returns a "chains" JSON object mapping chain name to chain id and a "chainProperties" JSON object mapping chain id to a map of chain properties.

Applications currently using the NXT API without dependency on the new parent/child chain structure can simply set the "chain" parameter to the value "2" to migrate all API calls automatically to the Ignis chain.

APIs which accept the "holding" and "holdingType" parameters now require holding to be set to the chain ID when holdingType=0 (i.e. coin).

Transaction Identifier

In Ardor, transaction IDs are no longer composed of 64-bit numeric value but use the 256-bit transaction full hash represented as a 64 character hex string.

Therefore, APIs that accept transaction ID parameters or return it in the JSON fields has to be switched to using the full hash.

In most cases the existing parameter name containing the transaction id was replaced with the same parameter name + "FullHash" postfix or just with a "fullHash" field.

Examples:

• The getTransaction API uses the "transaction" parameter in NXT and the "fullHash" parameter in Ardor.

• The getOrderTrades API uses the "askOrder" parameter in NXT and the "askOrderFullHash" parameter in Ardor.

Note that unique entities such as assets, currencies and aliases are still using a 64 bit numeric id.

To switch from the transaction full hash to entity id use the fullHashToId API or in JavaScript specifically use the NRS.fullHashToId function in nrs.util.js

Entity Identifiers

For global derived entities such as Assets or Currencies, the 64-bit long IDs is still unique in Ardor and used in the corresponding APIs.

For child chain local entities, such as Polls and Digital Goods, the 64-bit IDs are still unique, but only within the same child chain and still used in their APIs.

For entities that are prunable, such as prunable messages, tagged data, and shufflings, the full 256-bit hash must be used as an id now, and the appropriate APIs have been changed.

Transaction Fees

For transactions on the parent chain there is no change in behavior.

For child chain transactions, assuming no other fee restrictions, specify feeNQT=-1 to let the server calculate the minimum fee in ARDR and specify in the feeRateNQTPerFXT parameter the conversion rate between 1 child chain NQT to 1 whole Ardor unit.

The resulting transaction fee will be the minimum parent chain fee converted to child chain NQT according to the feeRateNQTPerFXT parameter.

Account Balances

The GetAccount API, no longer returns balanceNQT and unconfirmedBalanceNQT, since balances are now chain specific.

The GetBalance API should be used to get chain balances instead, or GetBalances for querying multiple chains.

Prices and rates

Prices and rates are now defined relative to a whole unit of the holding being bought or sold (asset, currency, coin), not to a QNT indivisible unit.

Therefore all priceNQT and rateNQT parameters and JSON fields have been renamed where appropriate to priceNQTPerCoin, priceNQTPerShare, rateNQTPerUnit, etc., to reflect their changed meaning of price per whole unit of each holding rather than per QNT.

All "units" parameters in the Monetary System APIs have been renamed to unitsQNT.

Transaction Types and Byte Formats

The numbering of some transaction types has changed between NXT and Ardor.

Transaction types specific to the Ardor chain use negative numbers, e.g. -1 for ChildChainBlock, -2 for Ardor ordinary payment.

Some transaction sub types have been moved to a separate type, e.g. voting and phasing related transactions have been moved out of Messaging to a new Voting transaction type.

The output of the getConstants API can be used to obtain a full list of the current transaction types and subtypes.

The transaction bytes format has also changed, adding a chain id, reorganizing the ordering of attachment and appendix bytes, and allowing prunable attachment parts to also optionally be represented in the bytes format

Phasing and Account Control

Phasing parameters which refer to transaction IDs now use transaction full hashes instead, prefixed with the chain ID separated by the colon character.

It is possible to refer to transactions on another chain when approving a phased transaction, or setting up a by-transaction phasing voting model.

The controlMaxFees parameter when setting mandatory approval now accepts multiple values, each fee being prefixed with the child chain ID and ':', to indicate which child chain the limit applies to.

If no max fee has been set for a child chain, there is no phasing transactions fees total limit on it for the controlled account.