Almonte at 16:56, 15 April 2021

2021-04-15T16:56:27Z

New page

<languages />
{{#seo:
|title=Ardordocs - Ardor API
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki, API, API documentation, Application program interface
|description=Description and examples of the API of Ardor.
}}
__TOC__

<translate>
==Description== 
The Ardor API allows interaction with Ardor nodes using HTTP requests to port 27876. Most HTTP requests can use either the GET or POST methods, but some API calls accept only the POST method for security reasons. Responses are returned as JSON objects.


If you want to interact with an [[Testnet|Ardor testnet local node]], please be aware that the port for sending the HTTP requests is different, you should use 26876 instead of the mainnet one 27876.


Each API call is documented ([[All_Operations_index|see the full API list]]), with definitions given for HTTP request parameters and JSON response fields, followed by an example:
*The JSON response fields are each followed by one of ''S'' for string, ''A'' for array, ''O'' for object, ''N'' for number or ''B'' for boolean.
*In the examples, the Ardor node is represented as ''localhost'' and requests and responses are formatted for easy reading; line breaks and spaces are not actually used except in some parameter values. All requests are in URL format which implies the HTTP GET method. When GET is allowed, the URL can be entered into a browser URL field but proper URL encoding is usually required (e.g., spaces in a parameter value must be replaced by ''+'' or ''%20''). Otherwise, the URL should be used as a guide to preparing an HTTP POST request using cURL, for example.


All API calls can be viewed and tested at http://localhost:27876/test while the local server node is running. For specific API calls, use 'http://localhost:27876/test?requestType='''specificRequestType''''


There are some [[Sample_Java_Programs|Sample Java Programs]], which demonstrate how to perform operations such as calculating the best bundling fee for child chain transactions, the use of APIs locally without relying on a remote node among others.


This document corresponds to Ardor Software Version {{NRSVersion}}: [https://www.jelurida.com/sites/default/files/Ardor-Developers-Cheat-Sheet.pdf Download Ardor Developers Cheat Sheet]
<accordion parent="accordion" heading="Ardor developers cheat sheet">
'''Java Conversion Functions'''


{| class="wikitable"
|-
! '''From'''
! '''To'''
! '''Code'''
|-
| ''Secret Phrase''
| ''Public Key''
| <code>Crypto.getPublicKey(String s)</code>
|-
| ''Public Key''
| ''Numeric ID''
| <code>Account.getId(byte[] pk)</code>
|-
| ''Numeric ID''
| ''Public Key''
| <code>Account.getPublicKey(long id)</code>
|-
| ''Numeric ID''
| ''String ID''
| <code>Long.toUnsignedString(long id)</code>
|-
| ''String ID''
| ''Numeric ID''
| <code>Convert.parseUnsignedLong(String s)</code>
|-
| ''Numeric ID''
| ''RS Format''
| <code>Convert.rsAccount(id)</code>
|-
| ''RS Format or String ID''
| ''Numeric ID''
| <code>Convert.parseAccountId(String s)</code>
|-
| ''byte[]''
| ''Hex String''
| <code>Convert.toHexString(b)</code>
|-
| ''Hex String''
| ''byte[]''
| <code>Convert.parseHexString(hex)</code>
|-
| ''Full Hash''
| ''ID''
| <code>Convert.fullHashToId(byte[] b)</code>
|-
| ''Epoch Time''
| ''Time Millis''
| <code>Convert.fromEpochTime(int t)</code>
|-
| ''Time Millis''
| ''Epoch Time''
| <code>Convert.toEpochTime(long t)</code>
|-
| ''String''
| ''byte[]''
| <code>Convert.toString(byte[] b, Boolean isText)</code>
|-
| ''byte[]''
| ''String''
| <code>Convert.toBytes(String s, boolean isText)</code>
|}


'''Java Common Operations'''


{| class="wikitable"
|-
! '''Operation'''
! '''Code'''
! '''Return'''
|-
| ''Sign''
| <code>Crypto.sign(byte[] message, String secretPhrase)</code>
| <code>byte[]</code>
|-
| ''Verify''
| <code>Crypto.verify(byte[] signature, byte[] message, byte[] publicKey)</code>
| <code>Boolean</code>
|-
| ''Encrypt''
| <code>Account.encryptTo(byte[] publicKey, byte[] data, String senderSecretPhrase, boolean compress)</code>
| <code>EncryptedData</code>
|-
| ''Decrypt''
| <code>Account.decryptFrom(EncryptedData encryptedData, String recipientSecretPhrase, boolean uncompress)</code>
| <code>byte[]</code>
|-
| ''Sha256''
| <code>Crypto.sha256().digest(byte[] b)</code>
| <code>byte[]</code>
|-
| ''Compress''
| <code>Convert.compress(byte[] bytes)</code>
| <code>byte[]</code>
|-
| ''Uncompress''
| <code>Convert.uncompress(byte[] bytes)</code>
| <code>byte[]</code>
|}


'''Useful Constants''' see <code>nxt.Constants</code> class


'''Reading from properties file''' <code>Nxt.getBooleanProperty(), Nxt.getIntProperty(), Nxt.getStringProperty(), Nxt.getStringListProperty()</code>


'''Javascript Conversion Functions'''


{| class="wikitable"
|-
! '''From'''
! '''To'''
! '''Code'''
|-
| ''Secret Phrase''
| ''Public Key''
| <code>NRS.getPublicKey(converters.stringToHexString(secretPhrase))</code>
|-
| ''Public Key''
| ''String ID''
| <code>NRS.getAccountIdFromPublicKey(publicKeyHexString)</code>
|-
| ''String ID''
| ''Public Key''
| <code>NRS.getPublicKey(id, true)</code>
|-
| ''String ID''
| ''RS Format''
| <code>NRS.convertNumericToRSAccountFormat(id)</code>
|-
| ''byte[]''
| ''Hex String''
| <code>converters.byteArrayToHexString(bytes)</code>
|-
| ''Hex String''
| ''byte[]''
| <code>converters.hexStringToByteArray(hex)</code>
|-
| ''Full Hash''
| ''ID''
| <code>NRS.fullHashToId(fullHash)</code>
|-
| ''Epoch Time''
| ''Time Millis''
| <code>NRS.fromEpochTime(epochTime)</code>
|-
| ''Time Millis''
| ''Epoch Time''
| <code>NRS.toEpochTime(time)</code>
|-
| ''String''
| ''byte[]''
| <code>NRS.getUtf8Bytes(String), converters.stringToByteArray(String)</code>
|-
| ''byte[]''
| ''String''
| <code>converters.byteArrayToString(bytes)</code>
|-
| ''NQT''
| ''Chain tokens''
| <code>NRS.intToFloat(amountNQT, decimals)</code>
|-
| ''NQT''
| ''formatted''
| <code>NRS.formatQuantity(amountNQT, decimals) – many different variants</code>
|-
| ''Chain tokens''
| ''NQT''
| <code>NRS.floatToInt(amountNXT, decimals)</code>
|}


'''Javascript Common Operations'''


{| class="wikitable"
|-
! '''Operation'''
! '''Code'''
! '''Return'''
|-
| ''Sign''
| <code>NRS.signBytes(hexStringMessage, secretPhrase)</code>
| <code>Hex String</code>
|-
| ''Verify''
| <code>NRS.verifySignature(hexSignature, hexStringMessage, hexPublicKey, callback)</code>
| <code>boolean</code>
|-
| ''Encrypt''
| <code>NRS.encryptNote(), NRS.encryptData() – see test.nrs.encryption.js</code>
| <code>encrypted message, nonce</code>
|-
| ''Decrypt''
| <code>NRS.decryptNote(), NRS.decryptData() - see test.nrs.encryption.js</code>
| <code>Decrypted message, shared key</code>
|-
| ''Sha256''
| <code>CryptoJS.algo.SHA256.create(), update(), finalize()</code>
| <code>word array</code>
|-
| ''Compress''
| <code>pako.gzip(new Uint8Array(bytes))</code>
| <code>byte array</code>
|-
| ''Uncompress''
| <code>pako.inflate(new Uint8Array(bytes))</code>
| <code>byte array</code>
|}


'''Useful Constants''' see <code>nrs.constants.js</code> class


'''Reading account settings'''
<code>NRS.settings[<setting name>]</code> - account specific
<code>NRS.mobileSettings[<setting name>]</code> - device specific
</accordion>

==General Notes== 
===Flexible Account IDs===
All API requests that require an account ID accept either an account number or the corresponding [[RS_Address_Format|Reed-Solomon address]].

===Quantity Units amountNQT, QNT and priceNQTPer(Share, Coin, Unit, etc.)=== 
The Ardor system is defined relative to a whole unit of the holding being transactioned. The parent chain ARDOR has a currency ARDR used to quantify value of forging in the system. Like all currencies, ARDR circulates in the system, moving from one user to another by transfers. Also, a small fee is required for every transaction, including those in which no ARDR is transferred, such as simple messages when using a child chain. This fee goes to the owner of the node that forges (generates) the new block containing the transaction that is accepted onto the blockchain, and the bundlers get the child chain fees and pay the ARDR fees to the forgers.


One billion ARDR were distributed during the snapshot, and no new ARDR will ever be created. ARDR is divisible to eight decimal places. Yet internally, the currency is still stored in integer form in units of amountNQT, where 1 ARDR = 10<sup>8</sup> amountNQT. All parameters and fields in the API involving a quantity of a token are denominated in units of amountNQT, for example ''feeNQT''.


The Ardor system can be thought of as an asset owned by all who possess ARDR. In this sense, ARDR quantifies ownership of or stake in the system. Stakeholders are entitled to forge blocks and collect transaction fees in proportion to the amount of ARDR they possess.


Other assets can be created within ARDR using [[Asset_Exchange#Issue_Asset|Issue Asset]] within a child chain (eg Ignis). The issuer must specify the number of decimal places to use in quantifying the asset, and the amount of the asset to create in generic units of QNT or Quant. Quantities of assets are stored internally as integers in units of QNT, and assets are priced at priceNQTper(Share, Coin, Unit, etc.)


For example, an ABTC (it represents Bitcoin) asset is divisible to eight decimal places, like the original bitcoin (BTC). Therefore a QNT of ABTC is equivalent to a Satoshi (10<sup>-8</sup> BTC). To place an order to sell 25,000,000 QNT of the ABTC asset at a price of 20,000 priceNQTperShare, use the API Call [[Asset_Exchange#Place_Order|Place Order]] with ''requestType''=''placeAskOrder'', ''quantityQNT''=25000000 and ''priceNQTPerShare''=20000 in the chain Ignis. If the entire quantity is sold on the Asset Exchange, the seller will receive 500,000,000,000 NQT (''quantityQNT'' * ''priceNQT'') from the buyer(s). This trade corresponds to selling 0.25 ABTC for 5,000 IGNIS, which is how the trade appears in the [[Ardor_client_interface|NRS client]]. In this case, the price of 20,000 in priceNQTperShare is also the price in Ignis per ABTC, since both ABTC and Ignis are divisible to eight decimal places.


Currencies in the Ardor [[Monetary_System#Monetary_System_Operations|Monetary System]] are a special kind of asset with properties and exchange methods suitable for currencies. Concerning quantities, exchange rates, and decimal places, the Monetary System API calls use amountNQT, QNT, and priceNQTPer(Share, Coin, Unit, etc.) in the same way as assets.

===Creating Unsigned Transactions=== 
All API requests that create a new transaction will accept either a ''secretPhrase'' or a ''publicKey'' parameter:
*If ''secretPhrase'' is supplied, a transaction is created, signed at the server, and broadcast by the server as usual.
*If only a ''publicKey'' parameter is supplied as a 64-digit (32-byte) hex string, the transaction will be prepared by the server and returned in the JSON response as ''transactionJSON'' without a signature. This JSON object along with ''secretPhrase'' can then be supplied to [[Transactions#Sign_Transaction|Sign Transaction]] as ''unsignedTransactionJSON'' and the resulting signed ''transactionJSON'' can then be supplied to [[Transactions#Broadcast_Transaction|Broadcast Transaction]]. This sequence allows for offline signing of transactions so that ''secretPhrase'' never needs to be exposed.
*''unsignedTransactionBytes'' may be used instead of unsigned ''transactionJSON'' when there is no encrypted message. Messages to be encrypted require the ''secretPhrase'' for encryption and so cannot be included in ''unsignedTransactionBytes''.

===Escrow Operations=== 
All API requests that create a new transaction will accept an optional ''referencedTransactionFullHash'' parameter which creates a chained transaction, meaning that the new transaction cannot be confirmed unless the referenced transaction is also confirmed. This feature allows a simple way of transaction escrow:
*Alice prepares and signs a transaction A, but doesn't broadcast it by setting the ''broadcast'' parameter to ''false''. She sends to Bob the ''unsignedTransactionBytes'', the ''fullHash'' of the transaction, and the ''signatureHash''. All of those are included in the JSON returned by the API request. (Warning: make sure not to send the signed ''transactionBytes'', or the ''signature'' itself, as then Bob can just broadcast transaction A himself).
*Bob prepares, signs, and broadcasts transaction B, setting the ''referencedTransactionFullHash'' parameter to the ''fullHash'' of A provided by Alice. He can verify that this hash indeed belongs to the transaction he expects from Alice, by using [[Transactions#Calculate_Full_Hash|Calculate Full Hash]], which takes ''unsignedTransactionBytes'' and ''signatureHash'' (both of which Alice has also sent to Bob). He can also use [[Transactions#Parse_Transaction|Parse Transaction]] to decode the unsigned bytes and inspect all transaction fields.
*Transaction B is accepted in the unconfirmed transaction pool, but as long as A is still missing, B will not be confirmed, i.e. will not be included in the blockchain. If A is never submitted, B will eventually expire -- so Bob should make sure to set a long enough deadline, such as the maximum of 32767 minutes.
*Once in the unconfirmed transactions pool, Bob has no way of recalling B back. So now Alice can safely submit her transaction A, by just broadcasting the ''signedTransactionBytes'' she got in the first step. Transaction A will get included in the blockchain first, and in the next block, Bob's transaction B will also be included.
Note that while the above scheme is good enough for a simple escrow, the blockchain does not enforce that if A is included, B will also be included. It may happen due to forks and blockchain reorganization, that B never gets a chance to be included and expires unconfirmed, while A remains in the blockchain. However, it is not practically possible for Bob to intentionally cause such chain of events and to prevent B from being confirmed.

===Prunable Data=== 


Prunable data can be removed from the blockchain without affecting the integrity of the blockchain. When a transaction containing prunable data is created, only the 32-byte sha256 hash of the prunable data is included in the ''transactionBytes'', not the prunable data itself. The non-prunable signed ''transactionBytes'' are used to verify the signature and to generate the transaction's ''fullHash'' and ID; when the prunable part of the transaction is removed at a later time, none of these operations are affected.


Prunable data has a predetermined minimum lifetime of two weeks (24 hours on the [[Testnet]]) from the timestamp of the transaction. Transactions and blocks received from peer nodes are not accepted if prunable data is missing before this time has elapsed. After this time has elapsed, prunable data is no longer included with transactions and blocks transmitted to peer nodes, and is no longer included in the transaction JSON returned by general-purpose API calls such as Get Transaction; the only way to retrieve it, if still available, is through special-purpose API calls such as Get Prunable Message.


Expired prunable data remains stored in the blockchain until removed at the same time derived tables are trimmed, which occurs automatically every 1000 blocks by default. Use [[Debug#Trim_Derived_Tables|Trim Derived Tables]] to remove expired prunable data immediately.


Prunable data can be preserved on a node beyond the predetermined minimum lifetime by setting the ''nxt.maxPrunableLifetime'' property to a larger value than two weeks or to ''-1'' to preserve it indefinitely. To force the node to include such preserved prunable data when transactions and blocks are transmitted to peer nodes, set the ''nxt.includeExpiredPrunables'' property to ''true'', thus making it an archival node.


Currently, there are two varieties of prunable data in the Nxt system: prunable [[Messages#Arbitrary_Message_System_Operations|Arbitrary Messages]] and [[Tagged_Data#Tagged_Data_Operations|Tagged Data]]. Both varieties have a maximum prunable data length of 42 kilobytes.

===Properties Files=== 
The behavior of some API calls is affected by property settings loaded from files in the ''ardor/conf'' directory during Ardor server initialization. This directory contains the ''nxt-default.properties'' and ''logging-default.properties'' files, both of which contain default property settings along with documentation. A few of the property settings can be obtained while the server is running through the [[Server_info#Get_Blockchain_Status|Get Blockchain Status]] and [[Server_info#Get_State|Get State]] calls.


It is recommended not to modify default properties files because they can be overwritten during software updates. Instead, properties in the default files can be overridden by including them in optional ''nxt.properties'' and ''logging.properties'' files in the same directory. For example, a ''nxt.properties'' file can be created with the contents:


nxt.isTestnet=true


This causes the Ardor server to connect to the [[Testnet]] instead of the Mainnet.

===Admin Password=== 
The admin password protects the node from malicious external access. It is not related to your passphrase or seed, your account id nor your public key.
Some API functions take an adminPassword parameter, which must match the nxt.adminPassword property unless the nxt.disableAdminPassword property is set to true or the API server only listens on the localhost interface (when the nxt.apiServerHost property is set to 127.0.0.1).

====How to setup the Admin Password====
The setup is done in the node <code>nxt.properties</code> [[Faq#Node_configuration_using_the_nxt.properties|configuration file]]:
# Password that should be provided when executing protected (administrative) API requests.
# Please choose a decent password here. Preferably, use a password generator.
# Password protection is disabled and password is not needed when the API server only listens on the localhost interface, i.e. when <code>nxt.apiServerHost=127.0.0.1</code>
# Add the <code>nxt.adminPassword=<type here the password></code> entry
# Restart the node

The same value specified in nxt.adminPassword should be passed when calling any API which accepts adminPassword as parameter. When loading the wallet from a remote node enter this value in the account settings page "Administrator Password" field.

==== Operations that require Admin Password ==== 
The admin password is required for the following operations (partial list)
# For any query API such as getBlockchainTransactions to return more than 100 records
# Get and stop APIs for forging, bundling, funding monitor, and shuffler
# Access to the /dbshell page to execute SQL queries
# Various administrative APIs: All [[Debug#Debug_Operations|Debug Operations]] require adminPassword since they require some kind of privilege. On some functions, adminPassword is used to override the maximum allowed value for the lastIndex parameter, which is set to 100 by default by the nxt.maxAPIRecords property. Giving you the option to retrieve more than objects per request.

==== Admin Password API responses ====
API response errors and their meaning, as follows:
* "Administrator's password is not configured. Please set nxt.adminPassword" - you need to configure the admin password on the remote node.
* "adminPassword not specified" - password is configured on the remote node but is not specified by the API call
* "Incorrect adminPassword (the specified password does not match nxt.adminPassword)" - the password specified did not match the remote node password
* "Too many incorrect admin password attempts from ..." - you specified too many incorrect password attempts

===Roaming and Light Client Modes=== 
The remote node to use when in roaming and light client modes is selected randomly, but can be changed manually in the UI, or using the new [[Networking#Set_API_Proxy_Peer|set API Proxy Peer]] API, or forced to a specific peer using the ''nxt.forceAPIProxyServerURL'' property.


Remote nodes can be blacklisted from the UI, or using the [[Networking#Blacklist_API_Proxy_Peer|Blacklist API Proxy Peer]] API. This blacklisting is independent of peer blacklisting. The API proxy blacklisting period can be set using the ''nxt.apiProxyBlacklistingPeriod'' property (default 1800000 milliseconds).


API requests that require sending the secret phrase, shared key, or admin password to the server, for features like forging, shuffling, or running a funding monitor, are disabled when in roaming or light client mode.
</translate>

API - Revision history

Almonte at 16:56, 15 April 2021