Mint Worker Utility

Overview

The Java Mint Worker Utility is a reference tool for minting currencies in the Monetary system, included in 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.

Introduction

The Ardor Monetary System supports the creation of new currency units using proof of work process we call "minting".

The process works as follows: When issuing a currency the issuer selects the "Mintable" property and sets the initial minting difficulty, final minting difficulty and hashing algorithm. The difficulty then increases gradually from the initial difficulty to the final difficulty as the number of units in circulation increases.

Minters retrieve a target value based on the current difficulty, using the getMinitingTarget transaction, then work offline to find an nonce number which produces a hash smaller than the target value. Once finding such hash, minters submit a currencyMint transaction, providing the nonce to one of the peers, as a result, once the next block is confirmed by the network the minter account receives the new currency units, .

Mint Worker

In order to help minters get started quickly, the protocol provides a simple utility named "Mint Worker" which provides a Java based, reference implementation for minting currency units. We hope that in the future 3rd party developers will adapt this utility for use with CPUs, GPUs and Asics to optimize the hashing performance.

The mint worker supports the following configuration parameters defined in the standard nxt.properties file:

Configuration

nxt.mint.serverAddress - the address of the Ardor peer accepting the transactions. Defaults to "localhost".

nxt.mint.useHttps - set to true in order to connect to the Ardor peer using https.

nxt.mint.currencyCode - specifies the monetary system currency code of the currency to mint.

nxt.mint.secretPhrase - secret phrase of the account to which the new currency units are granted. This secret phrase is submitted to the peer with each mint transaction.

nxt.mint.unitsPerMint - specifies the number of units per mint for each mint transaction. This is the number of units credited to the minter account, however, minting difficulty increases linearly with the number of units, therefore small minters should define small number of units and large minters a larger number [default: 1 whole unit per mint] This field accepts decimal positions according to the currency decimals.

nxt.mint.threadPoolSize - number of threads used for hashing [default: 1 thread per CPU core]

nxt.mint.initialNonce - by default (or when setting the value to 0) the initial nonce is chosen randomly and increased by one on every hash calculation. Set this value when you like the hashing process to work deterministically, for example for testing purposes.

nxt.mint.isSubmitted - by default the mint worker does not actually submit the minting transaction. To submit the transactions automatically whenever a hash is solved set this value to true. Refer to the best practices section below.

nxt.mint.stopOnError - default false. Unless true, minting will continue even after an error occurs when sending the minting transaction to the server.

Example

nxt.mint.serverAddress=10.0.0.1

nxt.mint.useHttps=false

nxt.mint.currencyCode=MINTZ

nxt.mint.secretPhrase=hashhashhash

nxt.mint.unitsPerMint=12.5

nxt.mint.threadPoolSize=2

nxt.mint.initialNonce=0

nxt.mint.isSubmitted=false

Runtime

To execute the mint worker follow these steps:

Install Ardor

Configure the mint parameters as explained above

Start the Ardor node and update the blockchain

Once the node is started launch the mint worker by running mint.sh on Unix or mint.bat on Windows

The mint worker connects to the NXT node specified by the nxt.mint.serverAddress setting, to retrieve the minting parameters and submit the solution nonce.

Constraints

Only a single currencyMint transaction per Block/Currency/Account is accepted by the blockchain. When submitting more that one such transaction in a single block the transaction is rejected.

Each accepted currencyMint transaction pays a fee of 0.1 ARDR, therefore, make sure that the number of units minted in each currencyMint transaction worth much more than 0.1 ARDR according to the current currency exchange rate.

To prevent minters from submitting the same mint request more than once, Ardor peers maintain a counter per currency/account and make sure that this counter increases with every mint request. Since the counter is part of the hashed data this ensures that the same mint transaction is not accepted more than once. The mint worker takes care of increasing the counter with every mint, however, if you are minting the same currency from more than one machine, setup a different Ardor account (i.e. passphrase) for each machine so that your mint counters won't overlap.

Additional Best practices

Never set the isSubmitted flag to true unless you are absolutely sure what's you are doing. You may end up paying a lot of fees and spamming the blockchain.

Always start by minting 1 unit per mint and observe the log messages printed by the mint worker. Look at the hash rate and the number of seconds per transaction. Adjust the nxt.mint.unitsPerMint setting so that the mint worker solves no more than one hash per hour, but also consider that a single transaction cannot mint more than 1/10000 of the total unit supply.