Monetary system

Introduction

The Ardor Monetary System features a special asset class currency secured by the Ardor network and blockchain. Virtual currencies with a variety of customizable properties can be created in minutes without the need for specialized hardware or a preexisting user base.

This guide describes the Monetary System, which was available for the Ardor child chains since its launch. Usage examples apply to the Ardor Client Interface.

Monetary System Menu

The Monetary System is accessed by clicking on Monetary System in the left-pane menu area of the Ardor Client Interface, causing a submenu to appear:

Monetary System: This item expands or contracts the submenu below and opens the Exchange Booth screen, where exchangeable currencies can be traded.

Currencies: This item displays a list of all currencies and their properties as shown in the All Currencies Screen.

Exchange History: This item displays completed exchanges (trades) associated with the logged-in account.

Transfer History: This item displays completed transfers associated with the logged-in account.

Approval Requests: This item displays details of phased transactions associated with the logged-in account (see: currency approval requests)

Issue Currency: This item opens a pop-up entry form for issuing or re-issuing a currency as described in Issue a Currency.

All Currencies Screen

• The currency list is in order of most recently issued currencies.
• The currency list can be restricted by entering a Code/Name search pattern in the Search Currencies field at the top. The search pattern is case-insensitive and can include the wildcards * and ?.
• Clicking on a currency code in the Code column opens a detail pop-up window which includes a Currency Distribution link to a list of holders of the currency.
• Hovering over the symbols in the Type column reveals the Currency Types.
• The Current Supply is reduced when a reservable currency is claimed or increased when a mintable currency is minted.
• The Max Supply is the total supply of currency upon issuance for non-mintable currencies or the maximum supply of currency that can be achieved by minting.
• Clicking on a highlighted button in the Actions column opens the Exchange Booth screen or a pop-up entry form to reserve the currency, when applicable.
• Clicking on My Currencies in the upper right corner restricts the list to those currencies owned by the logged-in account as shown in the My Currencies Screen.

My Currencies Screen

• Clicking on a Transfer button opens the Transfer Currency pop-up entry form.
• Clicking on a highlighted Offer button opens the Publish Exchange Offer pop-up entry form, when applicable.
• Clicking on a highlighted Claim button opens the Claim Currency pop-up entry form, when applicable.
• Clicking on All Currencies in the upper right corner returns to the All Currencies Screen

Issue a Currency

To issue or reissue a currency, click on Issue Currency on the Menu. A pop-up entry form appears:

This entry form provides a few tips (by clicking on the green question marks), but some constraints on the fields are implied and only clarified through error messages that appear near the top of the form when improper values are specified. To minimize errors, follow these guidelines:

CURRENCY NAME: The name must be unique, three to ten characters long and longer than the currency code.

CURRENCY CODE: The code must be unique and composed of three to five upper case letters.

TYPE: Check the desired combination of currency types, subject these restrictions: Reservable requires exchangeable and/or claimable, as does controllable; but mintable requires exchangeable. Claimable requires reservable, non-mintable and zero initial supply. Refer to Currency Types below for more detail.

TOTAL SUPPLY: The total supply must equal the initial supply unless the currency is mintable or reservable. If mintable, the total supply is the maximum supply that can be achieved through minting. The total supply of a reservable currency is set at issuance to the reserve supply (entered as UNITS TO RESERVE in the reservable section of the form) and must be greater than the initial supply.

INITIAL SUPPLY: The supply of a mintable currency increases through the minting process; the initial supply (if any) is held by the issuer. The initial supply (if any) of a reservable currency is held by the issuer; but the initial supply of a claimable reservable currency must be zero.

DECIMALS: The number of allowed decimal places can be from zero to eight, but to avoid client rounding errors in rate calculations, it is recommended that a maximum of four decimal places be used.

ISSUANCE HEIGHT: This applies only to reservable currencies, and must be a blockchain height greater than the current value. Otherwise it must be zero.

FEE: The fee automatically adjusts to the number of letters in the currency code: 2500 ARDR for three-letter codes, 100 ARDR for four-letter codes and 40 ARDR for five-letter codes, check fees in here. The fee to reissue a currency is always 4 ARDR, but for thee- and four-letter codes the displayed fee must manually be overridden by clicking on advanced.

VOUCHER: See Transaction vouchers.

Currency Types

Following are further details about the six currency types:

Exchangeable

Exchangeable currencies can be traded for the child chain (eg: Ignis) currency in the Exchange Booth of the Ardor client, which operates differently than the Asset exchange. A currency owner can publish a combined buy/sell offer pair with an expiration block height and quantity limits. Only one active offer per account is permitted. Requests to buy or sell offered currency can submitted by anyone. These exchange requests are executed immediately (fully or partially) or not at all if no matching offers are found.

Controllable

Controllable currencies can only be transferred to and from the issuing account, and if also exchangeable only the issuing account can publish offers.

Reservable

If Reservable is checked, two extra fields appear:

AMOUNT TO RESERVE: This is the total amount of the currency to reserve, the reserve supply. It will become the total currency supply when the issuance height is reached, unless the minimum amount below is not achieved by then. It must therefore equal TOTAL SUPPLY and be greater than INITIAL SUPPLY.

MINIMUM AMOUNT OF TOKENS PER WHOLE UNIT NEEDED TO ACTIVATE CURRENCY: Assuming the currency code COIN, this is the minimum amount of child chain tokens (eg: Ignis) per COIN needed to back the currency. For example, if the reserve supply is set to 1000 COIN and the minimum amount per reserve unit is 0.2, then at least a combined 200 child chain tokens must be pledged by supporters to back the COIN currency before the issuance height. If this minimum requirement is met or exceeded in time, each pledged supporter becomes a founder and receives a portion of the difference between the initial supply and the reserve (now total) supply of the COIN currency. If the minimum is not met in time, the currency will be deleted and all pledged child chain tokens will be unlocked and returned to supporters. If the minimum is met or exceeded, all pledged child chain tokens will either remain locked until claimed if claimable or be transfered to the issuer otherwise.

Claimable

Claimable currencies are reservable currencies that allow the locked child chain tokens reserves that back them to be claimed, meaning that a current holder of a claimable currency can exchange it for the locked child chain tokens that backs it, in doing so reducing the Current Supply shown on the All Currencies Screen.

Mintable

If Mintable is checked, three extra fields appear:

MINIMUM DIFFICULTY: The minimum difficulty (minimum 1).

MAXIMUM DIFFICULTY: The maximum difficulty (maximum 255 and greater than the minimum).

ALGORITHM: The hashing algorithm to use. Select SHA256, SHA3, Scrypt, or Keccak25.

• A mintable currency is issued with an INITIAL SUPPLY of currency that can increase over time until the TOTAL SUPPLY is reached; thus TOTAL SUPPLY is better named MAXIMUM SUPPLY in this case.
• The currency supply is increased through a minting process, governed by the above properties. Minting does not secure the currency as mining does for some other virtual currencies such as Bitcoin; the currency is already secured by the Ardor blockchain and network.

Non-Shuffleable

Non-Shuffleable currencies will not participate in coin shuffling (an anonymity feature) when it becomes available in the future. The default is to participate.

Delete a Currency

A currency can be deleted only when the total supply belongs to one account, and only by using the Delete Currency API call. However, a currency that can be deleted can also be reissued with different properties using Issue a Currency.

Transfer a Currency

To transfer a quantity of currency to another account, click on the Send Currency button at the top of the Ardor Client Interface. Alternatively, click on the Transfer link on the My Currencies Screen, or navigate to the Exchange Booth for the currency and click on the Transfer link there. The Transfer Currency pop-up entry form appears:

Recipient: Enter the recipient account ID.

Units: Enter the number of currency units to transfer, up to the number of Currency units available.

Exchange an Exchangeable Currency

Currency exchanges take place in the Exchange Booth, which appears when Monetary System is clicked on the Menu or when the Exchange link is clicked on the All Currencies Screen:

• Click on the Offer link at the top to publish a buy/sell offer pair. Refer to Publish an Exchange Offer for details. Published offer pairs are displayed in the middle row, in order of most favorable rate.
• Click on the green bar to request to buy offered currency with child chain tokens (eg: Ignis). Open offers to sell currency for Ignis are displayed just below. Refer to Submit an Exchange Request for details.
• Click on the red bar to request to sell currency for offered child chain tokens. Open offers to buy currency with child chain tokens are displayed just below. Refer to Submit an Exchange Request for details.
• Exchange requests from the logged-in account to buy or sell offered currency are listed in the lower left area, most recent on top. If the request is italicized, it is pending. As soon as a pending request is confirmed (by inclusion in a block), it is executed based on available offers at that moment. All non-italicized requests have already been processed and possibly ignored if no matching offers were found. Old offers continue to be displayed until dropping off the bottom of the list, but they will not be processed again even if a new matching offer appears.
• Executed exchange requests (trades) from all accounts are listed in the lower right area, most recent on top. Click on My Exchanges to display only those associated with the logged-in account. This list is short; old exchanges (trades) fall off the bottom. For a complete list, click on Exchange History on the Menu

Publish an Exchange Offer

The Publish Exchange Offer pop-up entry form appears when the Offer button is clicked on the Exchange Booth screen, or alternatively on the My Currencies Screen:

Buy units (Initial): The initial amount of currency offered to buy.

Buy units (Limit): The total amount of currency to buy.

Buy Rate per unit: The exchange rate offered to buy currency (in child chain tokens (eg: Ignis) per unit of currency).

Sell units (Initial): The initial amount of currency offered to sell.

Sell units (Limit): The total amount of currency to sell.

Sell Rate per unit: The exchange rate offered to sell currency (in child chain tokens (eg: Ignis) per unit of currency).

Expiration Height: The block height at which the offer expires; it must be greater than the current height.

• Whenever an exchange request is executed against an offer, the respective limit is reduced by the amount of the exchange (trade).
• An offer pair, once published, will persist until the expiration height is reached or until both limits become zero. If one limit becomes zero before the other, that half of the offer pair is withdrawn.
• The offered amounts can decrease or increase from their initial values; they decrease when an exchange request is executed, but they increase when an exchange request of the opposite type is executed if the limit permits.
• Only one active offer is permitted per account; new offers replace existing offers.

Submit an Exchange Request

The Exchange Request drop-down entry forms appear when the green and red bars are clicked in the Exchange Booth:

The green buy request form has identical fields to the red sell request form. Only the direction of the exchange (trade) is different.

Units: The amount of currency to exchange. When selling, it sets the exchange limit rather than Total, meaning that Units will not be exceeded but Total could be exceeded.

Rate: The least favorable (to the requester) exchange rate (in child chain tokens per unit of currency) required. The request will be executed at a more favorable rate if possible.

Total: The amount of child chain tokens to exchange. This read-only field is automatically computed as Units * Rate. When buying, it sets the exchange limit rather than Units, meaning that Total will not be exceeded but Units could be exceeded.

Fee: The minimum and default fee for a request is 0.01 child chain tokens.

• The exchange request is submitted when the blue Exchange button is clicked, but will not be executed until confirmed (included in a block). Once confirmed, the request will be immediately executed (fully or partially) if any matching offers are found, otherwise it will be permanently ignored.

Exchange Example

Offer

Complete the offer form as follows:

• Buy units (Initial): 5
• Buy units (Limit): 10
• Buy Rate per unit: 1
• Sell units (Initial): 10
• Sell units (Limit): 20
• Sell Rate per unit: 2

Once the offer is confirmed on the blockchain, the Exchange Booth screen shows:

Request to Buy

Complete the green buy request form as follows:

• Units: 20
• Rate: 2

While the request is pending, the Exchange Booth screen shows:

• While the request is pending, it is italicized.

Once the request is confirmed on the blockchain, the Exchange Booth screen shows:

• The Units, Rate and Total columns in the Exchange Requests and Executed Exchanges sections have the same units as on the request form. Units is the amount of currency exchanged, Rate is the exchange rate in child chain tokens per currency unit, and Total is the amount of child chain tokens exchanged, always equal to Units * Rate.
• The requested amount of currency was greater than the amount offered, and the offered rate was more favorable to the requester than the requested rate, so the offered amount and rate prevailed, as shown in the Executed Exchanges section.
• The request was executed immediately upon confirmation, but continues to be displayed in the Exchange Requests section. Even though the request was only partially filled, it becomes obsolete after execution; the request will not be fully met even if a new matching offer appears in the future.
• All of the initial amount of currency offered to sell (10 units) was sold, so the sell half of the offer pair was temporarily withdrawn. But it could reappear if the supply of currency to sell is replenished by a sell exchange request being executed against the buy offer. Up to 10 more units could be sold in this way, because the sell limit is now 10 units, having been reduced from 20 units.
• The amount of currency offered to buy increased from the initial 5 units to 10 units, the buy limit. It would have increased to 15 if the buy limit was 15 or greater, due to the 10 units sold. Thus the Exchange Booth allows an offer publisher the opportunity to automatically replenish sold currency.
• Clicking on a timestamp in the Exchange Requests section opens a detail pop-up window showing all executed exchanges resulting from a request; clicking on the timestamps of any of those executed exchanges opens an offer detail window, which in turn shows initial and current supplies and limits along with all executed exchanges against that offer, plus exchange totals. The offer detail window can also be opened by clicking on a height value in the Offers to Exchange section, and the request detail window can also be opened by clicking on a timestamp in the Executed Exchanges section.

Request to Sell

Complete the red sell request form as follows:

• Units: 20
• Rate: 1

Once the request is confirmed on the blockchain, the Exchange Booth screen shows:

• The requested amount of currency was greater than the amount offered, and the offered rate was more favorable to the requester than the requested rate, so the offered amount and rate prevailed, as shown in the Executed Exchanges section.
• All of the currency offered to buy (10 units) was bought, so the buy half of the offer pair was withdrawn permanently because the buy limit became zero.
• The amount of currency offered to sell increased from 0 units to 10 units, the remaining sell limit; the bought units replenished the currency supply and so the sell half of the offer pair reappeared.
• Notice that the buyer and seller are the same account. The Monetary System allows this but still charges a fee even though no currency or child chain tokens is actually exchanged. This is a method for effectively withdrawing an offer before it expires.

Reserve a Reservable Currency

The Reserve Currency pop-up entry form appears when the Reserve button is clicked on the All Currencies Screen:

Amount of child chain tokens per currency unit: This value is multiplied by the Reserve Supply amount to determine the amount of child chain tokens to be pledged to back the currency, displayed as Amount reserved.

• If the entered amount of child chain tokens, we will consider IGNIS, per currency unit is 1.5 and the reserve supply is 100, 150 IGNIS will be pledged to back the currency. This will be displayed as Amount of IGNIS reserved on the form if this read-only field is clicked.
• The minimum amount of IGNIS per unit of currency that must be pledged by all supporters of the currency combined in order to activate (issue) the currency is displayed as Activation Per Unit Reserve. This value was specified as MINIMUM AMOUNT OF IGNIS PER WHOLE UNIT NEEDED TO ACTIVATE CURRENCY on the Issue Currency form. The combined amount of IGNIS that must be pledged is this value multiplied by Reserve Supply.
• The amount of IGNIS per unit of currency already pledged by other supporters is displayed as Current Per Unit Reserve. The corresponding amount of IGNIS already pledged is this value multiplied by Reserve Supply.
• In this example, 200 IGNIS must be pledged by all supporters combined to activate (issue) the currency. 100 IGNIS have already been pledged; at least 100 IGNIS more is required. If 150 IGNIS are pledged now, the minimum will have been met (and exceeded) and the currency will be issued at the issuance height.

Founders

All pledges of support can be viewed on the Currency Founders pop-up window, which can be opened by clicking on the currency code on the All Currencies Screen then clicking on Click here to view this currency's Founders. If the minimum combined pledge is reached by the issuance height, the pledged supporters will become the founders of the currency. In this example, there are two pledged supporters:

• The Amount Reserved column shows the amount of child chain tokens, we will consider IGNIS, pledged by each supporter, which upon activation (issuance) becomes IGNIS reserve backing the currency. These values are computed by multiplying the Reserve Units (elsewhere named Reserve Supply) by the Amount per Unit column.
• The Founders Units column shows the portions of the currency Reserve Supply to be distributed among pledged supporters of the currency upon activation (issuance), in proportion to the Amount Reserved
• The Percent of Minimum column shows what percentage each supporter has contributed to meeting the minimum reserve requirement. If the total reaches 100%, the currency will be activated (issued) at the issuance block height. In this example, the total has already exceeded 100% and so the currency will be activated (issued) 5 blocks from now.
• If the minimum reserve requirement were not to be met in time, the currency would be deleted and all pledges would be returned. When the minimum is met or exceeded in time, all pledged IGNIS either remain locked until claimed if claimable or are transfered to the issuer otherwise.
• If the currency is activated (issued), the Founders table freezes as a permanent record, and the Reserve Supply becomes the total supply of the currency.

Claim a Claimable Currency

The Claim Currency pop-up entry form appears when the Claim button is clicked on the My Currencies Screen:

Number of units: The number of units of currency to claim up to the displayed maximum of Number of units to claim, the amount of currency held by the logged-in account.

• The Claim rate (in child chain tokens per currency unit) multiplied by the entered Number of units is the amount of child chain tokens that will be unlocked and transfered to the currency holder.
• In this example, if the maximum amount of 80 units is claimed, 40 child chain tokens will be transfered to the logged-in account, reducing the Current Supply shown on the All Currencies Screen by 80 units.

Mint a Mintable Currency

The Ardor client interface does not provide a minting mechanism. Minting requires a separate tool that makes use of following API calls:

• Get Minting Target returns a target hash; a nonce must be found such that its hash is less than the target hash. The difficulty of computing a valid nonce increases as the currency supply increases, according to the MINIMUM and MAXIMUM DIFFICULTY properties entered in the Issue a Currency form. The hashing algorithm applied to the nonce must be the one selected as the ALGORITHM property in that same form.
• Currency Mint submits the computed nonce in exchange for newly minted currency, increasing the Current Supply shown on the All Currencies Screen.

A reference minting tool that uses the API is the Java Mint Worker Utility, included with the Ardor Software. In its current form, it can only use a CPU for hashing computations. It is hoped that in the future it will be enhanced to include support for GPUs and ASICs.

Official Documentation

Overview The "Currency" entity is the basic building block of the Ardor Monetary System, currency has a unique name and code and uniqueness is guaranteed by the protocol, currencies can be deleted and their code can be reused under certain conditions.

The total currency supply is divisible into currency units. Like assets, currency units supports decimal positions implemented as a client side feature. The maximum number of currency units which can be issued per currency is similar to Ardor or Ignis i.e. 10^9 * 10^8. The actual maximum units supply is set by the currency issuer. The currency issuer is the account which issues the currency and pays the issuance fee. The issuer is responsible for setting the currency properties and in some configurations has additional control over the currency usage. Like asset balance, currency units can be transferred between accounts.

Currency Properties The currency entity supports several properties. Properties can be mixed and matched in various ways to compose the currency type. The currency type then controls the inner workings of the currency. The list of available currency properties is as follows:

EXCHANGEABLE - the currency can be exchanged with child chain tokens. Holders of the currency can publish an exchange offer specifying the buy and sell rate of the currency much the same as banks or currency exchanges publish their exchange rates . Each account can publish only a single exchange offer at any given time. Exchange offers has an expiry block after which they are no longer in effect. Buyers and sellers can issue exchange requests to match published exchange offers. Unlike asset bid/ask orders, exchange requests are not saved, they are either executed immediately (fully or partially) or not executed at all. A match of exchange offer with a buy or sell exchange request creates an exchange entity which represents the transfer of currency units in return to child chain balance and causes the relevant account balances to update. Issuing an exchange offer reduces the child chain tokens and currency balance of the offering account temporarily until the offer expires. Exchange offers also specifies a limit on the number of exchanged units which can be larger than the number of units offered. When a buy exchange request matches an exchange offer the number of units offered for sell is reduced and the number of units offered for buy is increased as long as the limit has not been reached. Once the exchange limit of an exchange offer has been reached, This exchange offer can no longer be used.

CONTROLLABLE - currency property suitable for currencies which need to track an external entity. It imposes the following limitations on the currency (1) Currency can be transferred only to/from the issuer account (2) only the issuer account can publish exchange offers. The issuer account can issue a large (practically infinite) supply of units in advance, then transfer units to accounts, or offer to exchange units, to reflect actual transactions which take place in an external system. The large supply of units in the issuer account can be used to mimic the effect of creating units out of nowhere to support features such as creating new units and interest payments.

RESERVABLE - currency units are not issued immediately. Instead the currency issuer sets a block height by which the currency is to be issued and a limit of child chain tokens per unit needed in order to issue the currency. Currency "founders" then spend their child chain tokens to reserve their currency stake. If the amount of child chain tokens per unit needed in order to issue the currency is not reserved before reaching the block height the issuance is cancelled and funds are returned minus fees. If the required reserve is allocated, the currency is issued and units are split between founders according to their proportional stake of invested child chain tokens. In case of rounding, leftovers are sent to the issuer account. See below discussion of usage scenarios for Reservable currency.

CLAIMABLE - currency units of resereable currency can later be claimed at the same child chain tokens per unit rate reached when reserving the currency. The ability to claim a currency at a certain rate imposes some practical limits on the rates in which users would want to exchange it. However claimable currency can also be exchanged if only for the purpose of exchanging the whole currency supply, so that the currency can be deleted.

MINTABLE - currency can be minted using proof of work algorithms much the same as Bitcoin. Unlike Bitcoin mining, minting currency does not secure the network (this is done by Ardor). Minting is used solely for creating new currency units and serve as the only mechanism to increase the number of available units after the currency issuance.

NON_SHUFFLEABLE - this property indicates that in the future this currency cannot participate in coin shuffling. By default currencies are allowed to participate in shuffling.

Properties are combined into an Integer bit mask designated as the Currency type.

Currency Exchange For exchangeable currency, each currency holder account, can publish a single exchange offer specifying the buy rate and sell rate vs child chain tokens and the number of units she is willing to exchange (which cannot exceed her available currency units and child chain tokens balance). Users can observe all currency exchange offers (intuitively similar to fiat exchange offices) and try to match them with buy/sell exchange requests. An exchange offer has an expiration height, as well as a limit on the total number of units which can be exchanged. When units are bought from an exchange offer the number of units to sell increases automatically and vise versa. The publisher can also limit the total transaction volume of currency units traded for a specific exchange offer.

Deleting a Currency Since the available currency codes are limited to 3, 4 or 5 uppercase letters, the total number of codes is limited to 26^3 + 26^4 + 26^5 - 1 = 12355927 unique values (The code "ARDOR" is reserved), it is likely that some of these codes will have value by themselves. Therefore deleting a currency is possible under certain conditions depending on the currency type. Users may re-issue a currency, or delete a currency and then issue a new currency, with the same code but with different properties. In order to delete or re-issue a currency an account must poses all the currency units (and additional conditions apply based on the currency type)

Creating new Currency Units The only way to create new currency units after issuing a currency is using proof of work minting. Other methods of creating units are susceptible to denial of service attacks and/or sock puppets and are therefore not allowed. The controlable currency type provides a partial solution for creating new units, by allowing the currency issuer account to treat her supply as a treasury and only consider units outside of this account as the total currency supply. This approach requires users to trust the currency issuer which can increase the currency supply at any time.

Minting Users can issue minting requests in order to mint additional currency units. Each minting request triggers a hash calculation based on the submitted data and the currency hash algorithm. The resulting hash code is compared to the target value derived from the current currency difficulty. Minimal and maximal currency difficulty values and minting algorithm are specified when issuing the currency and cannot be changed later. The expected number of hash calculations (i.e. difficulty) of minting the first unit is 2^minDifficulty while the difficulty of minting the last unit is 2^maxDifficulty. Difficulty increases linearly from min to max based on the ratio between the current number of units and the total supply. Difficulty increases linearly with the number of units minted per CurrencyMint request, small minters can mint only a few units per request while large minters can mint large number of units per request. The number of units per minting request is limited to 1/10000 of the total unit supply. Minting is limited to a single minting transaction per block/account/currency. Currency issuers can specify initial supply of units as a "pre-mint" supply assigned to the issuer account then use crowd funding by making the currency RESERVABLE and EXCHANGEABLE. Once the currency becomes active the delta between the current supply (reserved supply) and total supply can be minted. The NRS provides a Java based, reference implementation mInter, which can be used for minting. In practice we expect users to enhance this minter to calculate hash codes using their Asics or GPUs, trying to match the current target, and once solving a hash, submit a currency mint transaction (thus paying a fee). If indeed the hash code is smaller than the target the currency units are credited to the sender account.

See documentation of the reference implementation "Mint Worker" utility here #207

Store of Value The combination of RESERVABLE and CLAIMABLE properties can be used to allocate initial value for a currency by locking child chain tokens. Once the currency is activated the reserved child chain tokens are locked and the only way to release them is to claim back the currency units in return to child chain tokens. This provides the currency a value based on the locked child chain tokens balance. Note: locked child chain tokens do not participate in forging as is the parent chain Ardor the one that securizes the network, hence it is not an issue that large amount of child chain tokens become locked as currency store of value.

Crowd Funding The combination of RESERVABLE and EXCHANGEABLE properties can be used for crowd funding, in this configuration the child chain tokens balance reserved by founders, is not locked, instead it is sent to the currency issuer account once the currency becomes active. The issuer can use these child chain tokens for its operations and the founders cannot claim back their currency units, only exchange it based on the published exchange offers. Currency issuers can specify the initial supply as "pre mine" and founders get share the difference between the reserve supply (also named "pre-activation" supply) and the initial supply.

Fees Currency issuance fee is based on the length of the currency code (see fees)

3 Letters - 2500 ARDR

4 Letters - 100 ARDR

5 Letters - 4 ARDR

Re-issuing an existing currency with different properties costs 4 ARDR regardless of the number of the currency code length. All other currency transactions (as of today) has a fee of 0.01 ARDR depending on the bundling.

Unit conversion Currency is measured in units and like assets has decimal positions, however the blockchain maintains currency balances as a whole number (QNT). Therefore, for example, in case a currency has 2 decimal positions and the client has reserved 123.45 units. The "units" value submitted in the API call should be 12345. APIs using child chain tokens balances should send the value measured in NQT as usual. When specifying "rate" the API calculates the ratio between child chain tokens balances balance in NQT and currency balance in QNT.

Example: For a currency with 2 decimal positions. When submitting a buy exchange request for 12.34 units at a rate of 5.6 [child chain tokens balances/Unit] the values submitted to the currencyBuy transaction should be: units = 1234 i.e. units without decimal position or 12.34 * 10^2 rateNQT = 5600000 i.e. rate converted to NQT then divided by decimal position or 5.6 * 10^8 / 10^2

In order to prevent rounding problems when submitting information to the server, the UI enforces the following rule: If a currency has D decimal positions. Unit values cannot have more than D decimal positions and rate values cannot have more than (8-D) decimal positions. Therefore when issuing a currency, we do not recommend specifying more than 4 decimal digits so that conversion rates are also divisible to at least 4 decimal digits.

Disclaimer Before issuing a currency we recommend issuing a currency with the same properties on the testnet and experimenting with all parameters since these cannot be changed without deleting the currency.

This documentation reflects the actual code implemented as of this date.

External Links

• Nxter Magazine: The Nxt Monetary System