Release notes

This is the first release of the Ardor software, for testnet only. It represents the first milestone in the building of the Ardor platform.

New Features

The main new user-visible feature is the existence of a single forging chain, using the ARDR token, and multiple child chains, each with its own token.

Forging Chain

The Ardor chain is used to establish the proof-of-stake consensus, using ARDR balances only. It supports only a few transaction types: ordinary payments, balance leasing, and coin exchange. Prunable plain or encrypted message attachments are also supported, but not permanent or standalone arbitrary message transactions.

Child Chains

The child chains support all transaction types as previously implemented on the Nxt platform, with the exception of balance leasing which is only available on the Ardor chain, and tagged data extend transaction which has been removed as unnecessary. A child chain can optionally be configured to disable certain transaction types, which has been done for testing purposes on the EUR child chain, disabling the Asset Exchange and Digital Marketplace.

Coin Exchange

To allow trading of child chain coins to each other, and also between child chains and the Ardor chain, a new Coin Exchange module has been implemented.

For trading between child chain coins, the coin exchange transactions are submitted on the child chain of the coin being sold. For trading between a child chain coin and Ardor, the transaction is submitted on the Ardor chain regardless of whether it is a buy or sell, and the fees for such transactions are higher.

Bundling

The bundling process is used to group child chain transactions from a child chain into a transaction on the Ardor chain. Bundlers accept the fees from those child chain transactions, in the corresponding child chain coin, and pay fees in ARDR to the parent chain forgers. Bundlers can be started from the cogwheel/bundlers menu, defining the coin to ARDR exchange rate they accept, a limit on the total fees in ARDR a bundler will pay, and an optional overpay amount.

When a bundler is running, it checks the unconfirmed transactions pool every time a new transaction from the child chain being bundled arrives. If the transaction fee included by the transaction sender, in child chain coins, when converted to Ardor using the exchange rate accepted by the bundler is at least equal to the minimum Ardor fee required for this transaction, the bundler will generate a ChildBlock transaction, including in it this and all other currently unconfirmed child chain transactions satisfying this requirement.

The Ardor fee the bundler will include for the ChildBlock transaction is equal to the sum of the minimum required Ardor fees for each, plus the calculated overpay amount, if any. Such overpay amount is optional, and may be used by bundlers willing to pay more in order to have their transactions included in block instead of those of competing bundlers.

The new ChildBlock transaction will displace from the unconfirmed pool any ChildBlock transactions of the same child chain that include only a subset of the same child transactions.

When propagating through the network, ChildBlock transactions will only be accepted by peers if they either include child transactions not already included in other ChildBlock transactions the peer already has in its pool, or offer to pay a higher fee for the same transactions. This ensures the network is not flooded with ChildBlock transactions even if every node is running a bundler, and allows bundlers to compete for propagating their transactions through the network by offering to pay higher fees.

It is now possible for child transactions to be submitted with zero fees, in child chain coins. If a bundler is willing to pay the Ardor fees for those, they will be included in the blockchain in the ChildBlock created by such bundler.

To prevent the unconfirmed pool from being overfilled with such zero-fees child chain transactions, once the maxUnconfirmedTransactions limit (configured in nxt.properties, default 2000) has been exceeded, child chain transactions will be dropped unless a bundler has already submitted a ChildBlock transaction which includes them.

Bundlers advertise their accepted bundling rates to other peers, signing such rates announcements with the private key of the bundler's account. To prevent fake rates announcements, they can be filtered based on this account effective balance (default set in nxt.minBundlerBalanceFXT is 1000 ARDR).

The GetBundlerRates API can be used to retrieve known bundlers rates, again with optional filtering by minimum bundler effective balance.

Peer Networking

The peer networking has been fully re-written and optimized to use socket connections and binary messages instead of http and JSON.

Block and transaction propagation through the network has been optimized, by sharing with peers the inventory of transaction IDs in the unconfirmed pool or in recent blocks, and only propagating the missing ones, if any, when a new block is generated, or a child block is bundled.

The hallmark feature has been removed as it is not needed anymore, hallmarks are no longer supported.

New APIs

APIs of the new Coin Exchange feature:
ExchangeCoins, CancelCoinExchange, GetCoinExchangeOrder, GetCoinExchangeOrders,
GetCoinExchangeOrderIds, GetCoinExchangeTrade, GetCoinExchangeTrades,
GetExpectedCoinExchangeOrderCancellations, GetExpectedCoinExchangeOrders,
GetLastCoinExchangeTrade.

Bundling related APIs:
BundleTransactions, GetBundlers, GetBundlerRates, StartBundler, StopBundler.

Other new APIs:
GetBalances, GetEffectiveBalance, GetFxtTransaction.

API changes

All APIs that are now chain specific accept a new chain parameter. Either the chain name or the chain ID can be used.

Transaction IDs are no longer 64-bit longs but 256-bit hashes, necessitating changes in all APIs that accept transaction ID parameters or return such in the JSON fields. For transactions on the Ardor chain, 64-bit long IDs can still be used with the getFxtTransaction API, as those are enforced to be unique. For child chain transactions, the getTransaction API now requires a fullHash parameter, in addition to specifying the chain.

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.

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.

DividendPayment API accepts holding and holdingType parameters to allow paying dividends in another asset or MS currency. The amountNQTPerQNT parameter has been renamed to amountNQTPerShare and now refers to dividend amount in NQT per
a whole share of the asset rather than per QNT.

The GetAccount API no longer returns balanceNQT and unconfirmedBalanceNQT, as balances are now chain specific. The GetBalance API should be used to get chain balances instead, or GetBalances for querying multiple chains.

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

Since 0 is now a valid fee value for child chains, all CreateTransaction APIs will accept it, instead of using it as a request for the server to calculate and use the minimum fee. To let the server calculate the child transaction fee, a value of feeNQT=-1 should be used, and a new feeRateNQTPerFXT parameter must be supplied, to indicate the exchange rate to use when calculating the fee (since minimum fees can only be calculated in ARDR). If feeRateNQTPerFXT is also set to -1, the server will query the currently known bundlers rates for this child chain, also subject to the minBundlerBalanceFXT limit on effective bundler account balance, and use the best one for the fee calculation. As bundlers rates cannot be trusted blindly, the transaction will not be broadcasted in this case, the returned transaction JSON including the fees calculated should be reviewed by the user. The bundler rate used will be returned in the bundlerRateNQTPerFXT JSON field, -1 if no bundlers are known for the chain.

The following APIs have been removed: ExtendTaggedData, GetPhasingPolls, GetTaggedDataExtendTransactions, GetInboundPeers, MarkHost, DecodeHallmark.

Transaction types and bytes format

The numbering of some transaction types has changed, due to the internal reorganizations of the TransactionType classes. Transaction types on the Ardor chain use negative numbers, e.g. -1 for ChildChainBlock, -2 for Ardor ordinary payment. Some transaction subtypes 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 getConstants should be consulted for 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, for the purpose of sending them more efficiently over the peer to peer network.

The JSON transaction representation is still supported, even though it is no longer used in the peer networking. Some attachment fields have been renamed for consistency with the API changes - units to unitsQNT, priceNQT to priceNQTPerShare, rateNQT to rateNQTPerUnit, amountNQT for dividend payments to amountNQTPerShare, etc.

Entity IDs

As part of designing child chain transactions to be prunable, it is no longer possible to enforce uniqueness of the 64-bit transaction IDs for child chains. This affects the IDs of derived entities such as Assets, MS Currencies, Polls, Digital Goods, Shufflings, etc.

For global derived entities such as Assets or Currencies, the 64-bit long IDs are still unique and used in the corresponding APIs. Note however that this uniqueness is now only within the same object type, i.e. it is not guaranteed that an Asset and a Currency will not happen to have the same 64-bit long ID.

For child chain local entities, such as Polls and Digital Goods, the 64-bit IDs are still unique, but within the same child chain only, and still used in their APIs. Again, there is no uniqueness guarantee across different entity types anymore.

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.

Phasing and Account control

Only child chain transactions can be phased. Therefore, when account control is set for an account, it can no longer submit Ardor chain transactions.

Phasing parameters which refer to transaction IDs must now use transaction full hashes instead, prefixed with the chain ID separated with ':'. It is possible to refer to transactions on other chains 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.

Transaction selection, sorting, limits and fees

An Ardor chain block can contain up to 10 (ten) transactions, this including both native Ardor transactions and ChildBlock transactions. There is no total payload size limit.

A ChildBlock can contain up to 100 (one hundred) child transactions, subject to a total payload limit of 128 kbytes. Prunable child transaction parts are also counted towards the payload size limit.

There is a limit of one ChildBlock per Ardor block for each child chain.

As in Nxt, it is up to a block forger which transactions to include in a block and how to sort them. The default forger behaviour is to select transactions ordered by Ardor fee (not fee per byte as in Nxt, since there is no block payload limit), and then sort them based on arrival timestamp.

It is also up to the ChildBlock bundler which child transactions to include in a ChildBlock, and this selection can be customized by defining a custom filter in the nxt.bundlingFilter property. The default bundler behaviour is to select child transactions ordered by fee per byte, up to the count and payload limits of a child block, creating several child blocks if necessary. Within a child block, child transactions are sorted based on their full hash, but executed based on sorting them after adding the block hash to the child transaction hash, i.e. the execution order of child transactions within a block is deterministic but not predictable and not controllable by the bundler or by the forger. This is in order to prevent front-running of asset exchange and other trading orders.

Ardor fees from ChildBlock transactions paid to the block forger are shared with the previous three block forgers in 1:1:1:1 ratio. Other Ardor chain fees are fully kept by the block forger, and child block transaction fees (in child chain coins) are fully kept by the ChildBlock bundler.

The back fees sharing which was applied in Nxt for some other transactions types such as currency or asset issuance has been removed, however the limitations of one such transaction per block for scarce blockchain resources are preserved.

Default fee for Ardor chain transactions is 10 ARDR. Default fee for child chain transactions is 0.1 ARDR. A ChildBlock must contain at least one child chain transaction, but there is no minimum ChildBlock fee requirement, i.e. such a ChildBlock with a single transaction in it would require only 0.1 ARDR fee if this is the minimum fee for the child transaction it contains.

Fees for child chain transaction types have been scaled depending on their impact on the blockchain, e.g. asset issuance fees are still 1000 ARDR as assets are global and kept permanently. There is a 1 ARDR extra fee added to transactions that create a new account.

The above fees and limits are set for the current testnet only and are subject to change before the production mainnet release.

Testnet accounts

The testnet genesis block has been created based on account balances from the Nxt testnet, as of 2017/01/01 (block height 1061208). Users who had testnet accounts as of that height should find their ARDR and NXT testnet balances imported into this testnet, to ARDR and IGNIS tokens respectively, plus an approximately equivalent amount of BTC, USD, and EUR child chain coins for testing. To allow for developers testing and running forging and bundling nodes, account holdings have been reduced by 50% which have been allocated to developers accounts.

Upgrading from Nxt

The Ardor release is not an upgrade and does not in any way affect your existing Nxt account or client installation. Both Ardor and Nxt should be possible to run simultaneously on the same machine, as long as the hardware capacity allows it.

The included ArdorNxtComparison.pdf document summarizes the major differences between the Nxt and Ardor platforms, for those deciding which one is a better fit for their use case, or considering a migration from Nxt to Ardor. More documentation should be added as Ardor development and features mature and stabilize.

Source: https://nxtforum.org/nrs-releases/ardor-v2-0-0e/

Also see: Nxt 2.0: Ardor childchain blockchain platform