ArdorDocs - User contributions [en]

Account control/en

2021-08-17T15:04:32Z

FuzzyBot: Updating to match new version of source page

<languages />
{{#seo:
|title=Account Control
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki, account control, account control feature
|description=Explanation of the Account Control feature: Any account can be restricted to only be allowed to issue phased transactions subject to a specific voting model.
}}
[[Category:Features]]
__TOC__
==Description==
Any account can be restricted to only be allowed to issue phased transactions subject to a specific voting model. This is achieved by the account submitting a setPhasingOnly transaction using
the setPhasingOnlyControl API. The getPhasingOnlyControl API can be used to retrieve the status of an account phasing control, and getAllPhasingOnlyControls to get all accounts subject to phasing control with their respective restrictions. The account control feature relies on the [[Phasing (f)|Phasing]] feature and is available in both Nxt and Ardor.

In Ardor, 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 that 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. Currently, the UI only supports setting max fee for the current chain.

These features present some interesting account usage scenarios:
* Multi-signature account <ref>For a detailed step-by-step guide, you can have a look at the advance guide [[Emulating_Multi_Signature_Accounts_on_the_Blockchain|How to use the phasing feature to emulate multisig accounts in the Ardor platform]]</ref>
* Tagging an account as a "savings" account, with no ability to send tokens
* Using a locked account as an "escrow" account
* limiting the ability to transfer assets, aliases, or other entities from an account

==Setting Account Control==
To set account control on your account, click on the "Account Balance" tile.
[[File:Account.Control.Balance.png|figure 1|none|border|200px]]

Then select the "Account Control" tab then click on the "Setup Mandatory Approval" link.
[[File:Account.Control.Approval.Link.png|figure 2|none|border|400px]]

This will load the "Mandatory Approval" dialog.

In Ardor, select the "Control Approval Model" from the available approval models defined in the [[Composite_phasing#Setting_up_an_Approval_Model phasing|Approval Models]] page.

The rest of the parameters are explained using balloon text on the dialog. Use the same method to remove the account control from an account that is under account control, account control removal transaction is subject to the same account control restrictions.

[[File:account.control.png|figure 3|none|border|600px]]

==Using Account Control==
When creating a transaction from an account that is under account control. The additional widget appears on the transaction dialog. It allows the user to select the specific phasing height and links to the account control information.

[[File:account.control.on.create.transaction.png|||figure 4|none|border|600px]]

''Note: Some exchanges do not accept phased transactions. In such cases, the approach would be to transfer first into a non-controlled account ("Hot Wallet"), and from there transfer to the exchange.''

Translations:Account control/12/en

2021-08-17T15:04:26Z

FuzzyBot: Importing a new version from external source

==Using Account Control==
When creating a transaction from an account that is under account control. The additional widget appears on the transaction dialog. It allows the user to select the specific phasing height and links to the account control information.

Translations:Account control/10/en

2021-08-17T15:04:26Z

FuzzyBot: Importing a new version from external source

The rest of the parameters are explained using balloon text on the dialog. Use the same method to remove the account control from an account that is under account control, account control removal transaction is subject to the same account control restrictions.

Translations:Account control/8/en

2021-08-17T15:04:26Z

FuzzyBot: Importing a new version from external source

This will load the "Mandatory Approval" dialog.

Translations:Account control/5/en

2021-08-17T15:04:26Z

FuzzyBot: Importing a new version from external source

These features present some interesting account usage scenarios:
* Multi-signature account <ref>For a detailed step-by-step guide, you can have a look at the advance guide [[Emulating_Multi_Signature_Accounts_on_the_Blockchain|How to use the phasing feature to emulate multisig accounts in the Ardor platform]]</ref>
* Tagging an account as a "savings" account, with no ability to send tokens
* Using a locked account as an "escrow" account
* limiting the ability to transfer assets, aliases, or other entities from an account

Translations:Account control/4/en

2021-08-17T15:04:26Z

FuzzyBot: Importing a new version from external source

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. Currently, the UI only supports setting max fee for the current chain.

Translations:Account control/3/en

2021-08-17T15:04:26Z

FuzzyBot: Importing a new version from external source

Phasing parameters that refer to transaction IDs must now use transaction full hashes instead, prefixed with the chain ID separated with ':'.

Getting started/zh-hans

2020-08-11T01:01:34Z

FuzzyBot: Updating to match new version of source page

{{#seo:
|title=Getting started
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki
|description=Ardor documentation homepage - Getting started with the Ardor platform
}}
<languages />

[https://www.jelurida.com/ardor Ardor]是一个提供区块链服务的多链平台，它发展自经过时间考验且高效节能的[https://www.jelurida.com/nxt Nxt区块链].。Ardor 主网于2018年1月1日推出。通过本文档，您将熟悉Ardor平台的[[Features|广泛功能]]。通过了解Ardor的特色功能，您可以积累知识；通过学习《[[Basic tutorials|基本教程]]》，您可以考虑自己上手操作技术。对开发人员而言，我们为Ardor 250多个API中的每一个都提供了文档，这些[[API|API]]可用于快速、经济地部署dAPP和智能合约，以便将您的业务流程与Ardor区块链集成起来。请定期检查此网站以获取最新内容和相关更新，附加功能也会在此发布。

==下载Ardor==

在我们开始之前，如果您还没有这样做，那么请您检查您的电脑是否安装了正确的（通常是最新的）[https://adoptopenjdk.net/ Java]版本。您可以为您的平台使用任何Java兼容版本，所需的最低版本是Java 8，推荐版本是Java 11。我们通常使用OpenJDK 14进行测试。

首先从Ardor/[https://www.jelurida.com/ignis Ignis]开始，您必须先下载客户端（又称“钱包”）。客户端作为二进制包分发给以下平台：

[[File:200px-Windowslogo.jpg|100px|frameless|link=Getting_started#Windows]][[File:200px-AppleLogo.jpg|100px|frameless|link=Getting_started#MacOS]][[File:200px-Linuxlogo.jpg|130px|frameless|link=Getting_started#Linux]][[File:200px-RaspberryPi_Logo.png|100px|frameless|link=Getting_started#Raspberry_Pi]][[File:200px-Android.png|100px|frameless|link=Getting_started#Android]]

==客户端安装==

<accordion parent="accordion" heading="===Windows===">
#如果想要测试诸如新登录页面这样的最新功能，您可以从[{{NRSWinInstaller}} Windows]网址下载针对Ardor客户端{{NRSVersion}}最新官方版的Windows安装包。
#Ardor的Windows客户端是一个.exe文件。下载后，您可以通过执行完整性检查来验证其[[Faq#How_to_verify_authenticity_of_Ardor_installations|完整性]]。
#运行安装包，并按照屏幕上的说明进行操作。请注意，您可以在安装过程中选择测试网或主网。如果需要更多详细信息，请遵循[[How_to_download_the_ardor_client_wallet|步骤指南]]。默认情况下，安装后的图标将在桌面和“开始”菜单中创建。
#现在可以通过单击Ardor图标运行Ardor软件。几秒钟后，Ardor钱包会打开自己的窗口。
#如果您已创建Ardor账户，请单击“返回用户”输入您的密码。[[How_to_create_an_account_on_the_Ardor_Platform|如果您需要创建新的Ardor账户，请单击此处获取新账户创建说明]]。
</accordion>

<accordion parent="accordion" heading="===macOS===">

#如果想要测试诸如新登录页面这样的最新功能，您可以从{{NRSMacInstaller}}网址下载针对Ardor客户端{{NRSVersion}}最新官方版的Mac安装包。下载后，[[Faq#How_to_verify_authenticity_of_Ardor_installations|验证其签名]],并检查安装包的SHA256散列是否安全。
#运行安装包（Ardor的Mac安装包以.dmg格式打包），并按照屏幕上的说明操作：
## 点击Ardor安装包.app；[[File:MacInstaller_1.png|none|border|400px]]
## 出现安全警告，单击以绿色突出显示的“？”图标；[[File:MacOS_SecurityWarning_1.png|none|border|400px]]
## 单击弹出的窗口中的“为我打开常规窗格”；[[File:MacOS_SecurityWarning_2.png|none|border|400px]]
## 单击以绿色突出显示的锁进行更改；[[File:MacOS_SecurityWarning_3.png|none|border|400px]]
## 选项“无论如何都要打开”现在可用，单击此按钮（注意：如果没有显示，请暂时关闭Ardor安装窗口）；[[File:MacOS_SecurityWarning_4.png|none|border|400px]]
## 现在打开Ardor安装包.app，点击“打开”按钮；[[File:MacOS_SecurityWarning_5.png|none|border|400px]]
## 选择语言；[[File:MacInstaller_2.png|none|border|400px]]
## 单击“下一步”，开始安装；[[File:MacInstaller_3.png|none|border|400px]]
## 接受许可协议的条款；[[File:MacInstaller_4.png|none|border|400px]]
## 选择安装路径；[[File:MacInstaller_5.png|none|border|400px]]
## 选择要安装的软件包；[[File:MacInstaller_6.png|none|border|400px]]
## 检查选项“[[Tutorial_on_setting_up_the_ardor_testnet|“参阅设置Ardor测试网的教程”]][[File:MacInstaller_7.png|none|border|400px]]
## 安装完毕后，单击“完成”。[[File:MacInstaller_9.png|none|border|400px]]
#在“应用软件”中单击“ardor.app”，您便可运行Ardor软件。如果您已创建Ardor账户，请单击“返回用户”输入您的密码。[[How_to_create_an_account_on_the_Ardor_Platform|如果您需要创建新的Ardor账户，请单击此处获取新账户创建说明]]。
</accordion>

<accordion parent="accordion" heading="===Linux===">

以下是在Linux 64位平台上安装Ardor客户端的说明。32位安装说明非常类似，您只需下载32位版本的Java，而非64位版本的Java。

您也可以在Linux VPS上使用此说明。

====设置Java====
如果您已安装Java，则可以跳过此步骤。另外，您也可以通过发行库来安装，执行以下操作（针对Ubuntu/Debian版本）：

<pre>sudo apt更新
sudo apt安装openjdk-11-jre-headless</pre>

您还可以使用“openjdk-8-jre-headless”或任何其他Java 8+兼容版本。

====安装并运行Ardor客户端====

=====使用Unix安装包=====
您可以从[https://www.jelurida.com/ardor-client.sh ardor-client.sh]执行与大多数linux发行版兼容的unix安装包，并按说明进行操作。如果想要测试诸如新登录页面的最新功能，您也可以下载实验版本的[https://www.jelurida.com/ardor-client-experimental.sh ardor-client-experimental.sh]。

<pre>工作组https://www.jelurida.com/ardor-client.sh网站
sh组ardor-clinet.sh
</pre>

=====使用通用压缩包
=====
您可以按照以下更通用的说明进行操作：
#切换到主文件夹，并下载最新的客户端({{NRSVersion}})：<br /><code></code><br /><code>wget {{NRSDownload}}</code><code>wget https://www.jelurida.com/ardor-client.zip.asc</code> 并验证签名是否正确：<code>gpg --with-fingerprint ardor-client.zip.asc</code>
#解压：<br /><code>解压ardor-client.zip</code><br /><code>cd ardor</code>

=====运行Ardor客户端=====

#现在是启动软件的时候了。您可以从执行“<code>./run.sh</code> or <code>./run.sh --daemon</code>”开始在后台运行Ardor节点，您可以在Ardor目录中找到它。当您在窗口中看到类似以下内容的文本时，服务器将立即处于激活状态：“已成功启动<br/><code>Ardor服务器{{NRSVersion}} started successfully.</code>。该shell窗口将运行Ardor服务器并打印所有Ardor日志消息，因此它需要保持运行！<br />
#从web浏览器打开 http://localhost:27876/ 网址，以获取Ardor客户端。请注意，如果这是您第一次在您的机器中运行Ardor，则需要下载Ardor区块链的最新版本。根据您的网络连接速度，这可能需要几个小时。当区块链在下载中时，Ardor客户端将显示一个进度条。现在您可以[[How_to_create_an_account_on_the_Ardor_Platform|单击此处获取新账户创建说明]]。
#*注意：如果客户端安装在专用服务器或VPS上，则应将“localhost”更改为服务器/VPS IP。
</accordion>

<accordion parent="accordion" heading="===Raspberry Pi===">

要在Raspberry pi上安装Ardor客户端，[https://medium.com/@mrv_89306/solar-powered-ardor-blockchain-node-aa680a976c50 可以参考由太阳能电池板供电的Ardor客户机的实现说明。]
</accordion>

<accordion parent="accordion" heading="===安卓===">
[[Android_Full_Node|单击Android完整节点安装指南，]]并按说明进行操作。
</accordion>

==='''需要帮助？'''===
在下载或开发过程中需要帮助吗？您可以在[https://ardornxt.slack.com slack]##帮助台频道与我们联系，在[https://ardorforum.org Ardor论坛],与社区专家交流，并查看[[Faq|常见问题]]。您也可以在我们的[https://desk.zoho.eu/portal/jelurida/home 服务台]提交一个故障单。

==轻量级合约文档==
轻量级合约代表了在现有的Ardor api之上开发自动化层的设计框架，请参阅官方文档以了解有关此功能的更多信息：

<div class="noprint" style="float:none; border:1px solid black;width:95%;background-color:#F6F0F0;padding:2px;">
{| cellspacing="0"
| style="padding-left:50px;"| '''[[Lightweight_Contracts|轻量级合约文档]]'''
|}</div>
<noinclude>

==登录Ardor==
有不同的方式登录Ardor以创建账户，《[[Login_Page_Tutorial|登录页教程]]》中对此进行了说明。

==获取您的第一个ARDR==

安装Ardor客户端后，即可开始交易。要做到这一点，我们需要获取一些代币，无论是ARDR，还是IGNIS，亦或任何其他子链。Ardor主网是实时的，代币在许多主要交易所实时流通。

请注意，我们将在下一个示例中使用的代币来自测试网。这些代币不在交易所交易，也没有货币价值——它们的存在只是为了方便开发人员和愿意尝试这些功能的人士进行操作。

获取测试网代币的过程很简单。您可以在[https://ardorforum.org Ardor论坛]上提出要求，通过[https://ardornxt.slack.com slack] #帮助台频道与我们联系。此外，还有一个外部[https://www.ardor.world/faucet_ardor/ faucet]。

=== 交易所 ===

* [https://www.jelurida.com/ardor/explorers 目前正在交易ARDR]

==下一步==

按照《[[Basic_tutorials|基本教程]]》学习如何使用Ardor平台，或开始熟悉Ardor的大量内置[[Features|特色功能]]。

=== 铆接 ===

铆接的过程称为[[Forging_(f)|锻造]]。一旦你的ARDR超过1.000，你便可开始锻造，这样当你的节点生成一个块时，即可赚取交易费用。

此外，您还可以选择加入[[Node_Reward_Program|节点奖励计划]]，只需设置一个节点，该节点的API和对等端口对Internet以及公共和静态IP地址开放。

==反馈和错误==

如果在本文档中发现错误，我们希望尽快更正。请您将发现的问题发送至[mailto:info@jelurida.com info@jelurida.com]，我们会进行后续处理。

<accordion parent="accordion" heading="
最新的文档更改和更新
">
{{Special:SimpleChanges/days=150,limit=100,bots,hideminor,namespace=0}}
</accordion>

Getting started/en

2020-08-11T01:01:34Z

FuzzyBot: Updating to match new version of source page

{{#seo:
|title=Getting started
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki
|description=Ardor documentation homepage - Getting started with the Ardor platform
}}
<languages />

[https://www.jelurida.com/ardor Ardor] is a blockchain-as-a-service multi-chain platform that evolved from the time-tested and energy-efficient [https://www.jelurida.com/nxt Nxt blockchain]. The Ardor mainnet launched on 01 January 2018. Through this documentation, you will learn all about the extensive capabilities of the Ardor platform. Begin developing your knowledge by reading about each of Ardor’s distinctive [[Features]] or consider trying the technology yourself by following some [[Basic tutorials|Basic Tutorials]]. For developers, documentation is provided for each of Ardor’s more than 250 [[API|APIs]] that can be used to quickly and cost-effectively deploy dApps and smart contracts that integrate your business processes with the Ardor blockchain. Check this site regularly for new content and updates as additional features are released.

==Download Ardor==

Before we begin, if you haven’t already done so, you may wish to check that you have the correct (usually most recent) version of [https://adoptopenjdk.net/ Java] installed on your computer. You can use any compatible Java available for your platform. The minimum required version is Java 8. The recommended version is Java 11. We usually test with OpenJDK 14.

To start with Ardor/[https://www.jelurida.com/ignis Ignis], you must first download the client, also known as a "wallet", on your machine. The client is distributed as a binary package for the following platforms:

[[File:200px-Windowslogo.jpg|100px|frameless|link=Getting_started#Windows]][[File:200px-AppleLogo.jpg|100px|frameless|link=Getting_started#MacOS]][[File:200px-Linuxlogo.jpg|130px|frameless|link=Getting_started#Linux]][[File:200px-RaspberryPi_Logo.png|100px|frameless|link=Getting_started#Raspberry_Pi]][[File:200px-Android.png|100px|frameless|link=Getting_started#Android]]

==Client Installation ==

<accordion parent="accordion" heading="===Windows===">
#Download the Windows installer for the latest official Ardor Client {{NRSVersion}} from {{NRSWinInstaller}}.
#Ardor's Windows client comes as an .exe file. After downloading it, you can verify its integrity by performing an [[Faq#How_to_verify_authenticity_of_Ardor_installations|integrity check]]
#Run the installer and follow the instructions on the screen. Note that you can select either the testnet or mainnet during installation, if further details are needed please follow the [[How_to_download_the_ardor_client_wallet|step-by-step guide]]. Once installed icons will be created by default in your desktop and Start Menu.
#You can now run the Ardor software by clicking on the Ardor icon. After a few seconds, the Ardor wallet will open in its own window.
#If you already have created an Ardor account, click in 'Returning User' to introduce your passphrase. If you need to create your Ardor account, [[How_to_create_an_account_on_the_Ardor_Platform|click here for instructions to Create a New Ardor Account]].
</accordion>

<accordion parent="accordion" heading="===MacOS===">

#Download the Mac installer for the latest official Ardor Client {{NRSVersion}} from {{NRSMacInstaller}}. After downloading, [[Faq#How_to_verify_authenticity_of_Ardor_installations|verify its signature]]. After downloading, check the SHA256 hash of the package for security.
#Run the installer package (Ardor's Mac installer comes packaged in .dmg format) and follow the instructions on screen
## Click on the ardor-installer.app [[File:MacInstaller_1.png|none|border|400px]]
## A security warning appears, click on the icon "?" highlighted in green [[File:MacOS_SecurityWarning_1.png|none|border|400px]]
## Click on the "Open the General pane for me" in the pop-up that appears [[File:MacOS_SecurityWarning_2.png|none|border|400px]]
## Click on the lock highlighted in green to make changes [[File:MacOS_SecurityWarning_3.png|none|border|400px]]
## The option "Open anyway" is now available. Click on this button (note: if it does not appear please close temporary the Ardor installation windows) [[File:MacOS_SecurityWarning_4.png|none|border|400px]]
## Now open the ardor-installer.app and click on the "Open" button [[File:MacOS_SecurityWarning_5.png|none|border|400px]]
## Select the language [[File:MacInstaller_2.png|none|border|400px]]
## Click on 'Next' to begin with the installation [[File:MacInstaller_3.png|none|border|400px]]
## Accept the terms of the license agreement [[File:MacInstaller_4.png|none|border|400px]]
## Select the installation path [[File:MacInstaller_5.png|none|border|400px]]
## Select the packages you want to install [[File:MacInstaller_6.png|none|border|400px]]
## Check the options [[Tutorial_on_setting_up_the_ardor_testnet|See the tutorial for setting up the Ardor testnet]] [[File:MacInstaller_7.png|none|border|400px]]
## Once installed, click on finish [[File:MacInstaller_9.png|none|border|400px]]
#You can now run the Ardor software clicking on the "ardor.app" in Applications. If you already have created a Ardor account, click in 'Returning User' to introduce your passphrase. If you need to create your Ardor account, [[How_to_create_an_account_on_the_Ardor_Platform|click here for instructions to Create a New Ardor Account]].
</accordion>

<accordion parent="accordion" heading="===Linux===">

Here is the guide to installing the Ardor Client on a Linux 64-bit platform. 32-bit installation instructions are very similar; you just might need to download the 32-bit version of Java instead of the 64-bit one.

You can use these instructions on your Linux VPS as well.

====Set up Java====
You can skip this step if you already have Java installed. Otherwise, you can install it via your distribution repository doing the following (for Ubuntu/Debian builds):

<pre>sudo apt update
sudo apt install openjdk-11-jre-headless</pre>

You can also use `openjdk-8-jre-headless` or any other Java 8+ compatible version.

====Install and run the Ardor Client====

=====Using the Unix installer=====
You can execute the unix installer executable compatible with most linux distributions from [https://www.jelurida.com/ardor-client.sh ardor-client.sh] and follow the instructions.

<pre>wget https://www.jelurida.com/ardor-client.sh
sh ardor-client.sh
</pre>

=====Using the Universal Zip Package=====
You can follow the more generic instructions as explained below:
#Change to your home folder and download the latest client (version {{NRSVersion}}):<br /><code>cd ~</code><br /><code>wget {{NRSDownload}}</code><code>wget https://www.jelurida.com/ardor-client.zip.asc</code> and verify that the signature is correct: <code>gpg --with-fingerprint ardor-client.zip.asc</code>
#Unzip it:<br /><code>unzip ardor-client.zip</code><br /><code>cd ardor</code>

=====Run the Ardor client=====

#Now it's time to start the software. You may start it by executing <code>./run.sh</code> or <code>./run.sh --daemon</code> for running the Ardor node in the background, which you will find in the ardor directory. The server will be active as soon as you see in the window a text similar to this: <br/><code>Ardor server {{NRSVersion}} started successfully.</code> This shell window will be running the Ardor server and print all the Ardor log messages, so it needs to stay running!<br />
#Open http://localhost:27876/ from a web browser to access the Ardor Client. Please note that, if it's the first time you run Ardor in your machine, the Ardor blockchain will need to be downloaded until it is up to date. Depending on the your network connection speed, this may take a few hours. The Ardor Client will show you a progress bar as the blockchain downloads. Now you can visit the [[How_to_create_an_account_on_the_Ardor_Platform|click here for instructions to Create a New Ardor Account]].
#*NOTE: If you've installed the client on a dedicated server or VPS, you should change "localhost" to your Server/VPS IP.
</accordion>

<accordion parent="accordion" heading="===Raspberry Pi===">

For installing the Ardor client on a Raspberry pi, you can refer to the description of [https://medium.com/@mrv_89306/solar-powered-ardor-blockchain-node-aa680a976c50 an implementation with the Ardor client powered by solar panels]
</accordion>

<accordion parent="accordion" heading="===Android===">
Click on the [[Android_Full_Node|Android Full Node installation guide]] and follow the instructions.
</accordion>

==='''Need help?'''===
Need help during the download or development process? Contact us on the [https://ardornxt.slack.com slack] #helpdesk channel, chat with community experts on the [https://ardorforum.org Ardor Forum], and take a look at the [[Faq|FAQ]]. You can also reach us opening a ticket in our [https://desk.zoho.eu/portal/jelurida/home helpdesk]

==Lightweight Contracts documentation==
Lightweight Contracts represent a framework for developing a layer of automation on top of the existing Ardor APIs, refer to the official documentation to read more about this feature:

<div class="noprint" style="float:none; border:1px solid black;width:95%;background-color:#F6F0F0;padding:2px;">
{| cellspacing="0"
| style="padding-left:50px;"| '''[[Lightweight_Contracts|Lightweight Contracts documentation]]'''
|}</div>
<noinclude>

==Login to Ardor==
There are different ways to login to Ardor to create an account. It is explained in the [[Login_Page_Tutorial|Login Page Tutorial]]

==Getting your first ARDR==

With the Ardor client installed, it is now time to start transacting. To do that, we need to get some tokens, be it ARDR, IGNIS, or any other childchain. The Ardor mainnet is live and actual tokens are in circulation across numerous major exchanges.

Note the tokens we will be using in the next examples are from testnet. These tokens are not traded in exchanges and have no monetary value -- they exist only as a convenience for developers and those willing to experiment with the features.

The process for receiving testnet tokens is simple. Ask for them in the [https://ardorforum.org Ardor Forum], contact us on the [https://ardornxt.slack.com slack] channel #helpdesk. There is an external [https://www.ardor.world/faucet_ardor/ faucet] as well.

=== Exchanges ===

* [https://www.jelurida.com/ardor/explorers Currently trading ARDR]

==Next steps==

Learn how to use the Ardor platform by following the [[Basic_tutorials|basic tutorials]] or start reading about Ardor's extensive built-in [[Features]].

=== Staking ===

The process of staking in Ardor is called [[Forging_(f)|Forging]]. Once you have more than 1.000 ARDR you can start forging, thus earning the transaction fees when a block is generated by your node.

Furthermore, you can also opted in to the [[Node_Reward_Program|Node Reward Program]] by just setting up a node with both the API and peer ports open to the Internet and a public and static IP address.

==Feedback and errors==

If an error in this documentation is found, we would love to be aware to correct it as soon as possible. Please write a question to [mailto:info@jelurida.com info@jelurida.com] and we will take care.

<accordion parent="accordion" heading="Latest documentation changes and updates">
{{Special:SimpleChanges/days=150,limit=100,bots,hideminor,namespace=0}}
</accordion>

Getting started/ko

2020-08-11T01:01:33Z

FuzzyBot: Updating to match new version of source page

{{#seo:
|title=Getting started
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki
|description=Ardor documentation homepage - Getting started with the Ardor platform
}}
<languages />

[https://www.jelurida.com/ardor Ardor]는 BAAS(blockchain-as-a-service)를 목적으로 하는 최초의 멀티체인 플랫폼으로, 2018년 1월 1일부터 메인넷을 통해 작동해 왔습니다. 블록체인 코어는 에너지 효율적이며 오랜 시간으로 안정성이 증명된 [https://www.jelurida.com/nxt Nxt 블록체인]을 기반으로 합니다. 이 문서는 독자들에게 Ardor 플랫폼의 광범위한 기능에 대해 쉽게 설명하기 위한 목적으로 작성되었습니다. Ardor의 독창적이면서도 다양한 [[Features|기능]]에 대해 알아보시고, 몇가지 [[Basic tutorials|기본 튜토리얼]]을 직접 따라 해 보시면서 익혀보세요. 또한 Ardor의 250개 이상의 [[API|API]] 각각에 대한 설명과 스마트 컨트랙트 사용에 대한 절차를 기술해 놓았으니, 개발자 분들은 이를 통해 쉽고 효율적으로 기존 프로세스에 블록체인을 통합하거나 dApp을 배포 하실 수 있으실 겁니다. 추후 신규 기능이 출시되면 이 사이트의 내용 또한 업데이트 될 예정이니, 정기적으로 새 콘텐츠나 변동사항이 있는지 확인 하십시오.

==Ardor 다운로드==

시작하기 전, 우선 귀하의 컴퓨터에 올바른 [https://adoptopenjdk.net/ Java]가 설치 되어 있는지(통상 최신 버전) 확인해 주십시오. 운영체제에 호환되는 Java를 설치 하시면 됩니다. 최소 요구사항은 Java 8이며, 권장 사항은 Java 11입니다. 일반적으로 OpenJDK 14를 이용해 테스트를 진행 합니다.

Ardor/[https://www.jelurida.com/ignis Ignis]를 사용하기 위해선 우선 사용하시는 컴퓨터에 "지갑"으로도 불리는 클라이언트를 설치 하셔야 합니다. 클라이언트는 아래 운영체제에 바이너리 패키지 형태로 배포 됩니다. :

[[File:200px-Windowslogo.jpg|100px|frameless|link=Getting_started#Windows]][[File:200px-AppleLogo.jpg|100px|frameless|link=Getting_started#MacOS]][[File:200px-Linuxlogo.jpg|130px|frameless|link=Getting_started#Linux]][[File:200px-RaspberryPi_Logo.png|100px|frameless|link=Getting_started#Raspberry_Pi]][[File:200px-Android.png|100px|frameless|link=Getting_started#Android]]

==OS별 설치 방법 ==

<accordion parent="accordion" heading="===Windows===">
#최신 공식 Ardor Client {{NRSVersion}}를 다운로드 하시려면 {{NRSWinInstaller}}에서,.
#Ardor의 Windows 클라이언트는 .exe 파일 형태로 제공됩니다. 다운로드 하신 후 파일 진위 여부를 확인 하시려면, [[Faq#How_to_verify_authenticity_of_Ardor_installations|integrity check]]을 수행 하시면 됩니다.
#설치 파일을 실행 하셔서 화면에 나오는 지침을 따라 주세요. 설치 과정 중 테스트넷 혹은 메인넷을 선택하실때 유의해 주세요. (메인넷 풀노드로 사용 하실 경우 계속 다음만 누르시면 됩니다.) 설치 중 좀 더 자세한 가이드가 필요하신 경우 [[How_to_download_the_ardor_client_wallet|step-by-step guide]]를 참조해 주세요. 설치가 완료되면, 시작메뉴와 바탕화면에 Ardor 아이콘이 생성됩니다.
#Ardor 아이콘을 클릭하시면 곧 새창이 열리면서 Ardor 클라이언트가 실행됩니다.
#기존 계정을 보유하고 계신경우, 'Returning User'를 클릭 하셔서 로그인 하시면 됩니다. 새로 Ardor 계정을 생성하는데 도움이 필요하시다면, [[How_to_create_an_account_on_the_Ardor_Platform|신규 계정 만드는 법]]을 참조해 주세요.
</accordion>

<accordion parent="accordion" heading="===MacOS===">

#최신 공식 Ardor Client {{NRSVersion}}를 다운로드 하시려면 {{NRSMacInstaller}}에서, 에서 Mac용 클라이언트를 다운로드 해 주세요. 필요하시다면, [[Faq#How_to_verify_authenticity_of_Ardor_installations|파일 서명 검증]]을 진행 하실 수 있습니다. 다운로드 후에 보안을 위한 패키지의 SHA256 해시 값을 체크 하실 수 있습니다.
#설치 파일(Mac용 Ardor 설치파일은 .dmg 형식으로 제공됩니다.)을 실행해 주시고, 화면의 화면에 나오는 지침을 따라 주세요.
## ardor-installer.app을 클릭하세요. [[File:MacInstaller_1.png|none|border|400px]]
## 보안 경고가 나타나면, 녹색의 "?"아이콘을 클릭하세요. [[File:MacOS_SecurityWarning_1.png|none|border|400px]]
## 팝업창이 나타나면 "일반 창으로 열기"를 클릭하세요 [[File:MacOS_SecurityWarning_2.png|none|border|400px]]
## 변경을 위해 녹색 좌물쇠를 클릭하세요. [[File:MacOS_SecurityWarning_3.png|none|border|400px]]
## "무시하고 열기"버튼이 활성화되면 클릭 하세요.(만약 나타나지 않는다면 임시로 켜진 Ardor 설치 프로그램을 종료하세요) [[File:MacOS_SecurityWarning_4.png|none|border|400px]]
## ardor-installer.app을 클릭 하신 후 "Open"을 클릭하세요. [[File:MacOS_SecurityWarning_5.png|none|border|400px]]
## 언어를 선택하세요.[[File:MacInstaller_2.png|none|border|400px]]
## 'Next'버튼을 눌러 설치를 시작하세요. [[File:MacInstaller_3.png|none|border|400px]]
## 라이센스 약관에 동의 하세요.[[File:MacInstaller_4.png|none|border|400px]]
## 설치 경로를 선택하세요.[[File:MacInstaller_5.png|none|border|400px]]
## 설치 하고자 하는 패키지를 선택하세요.[[File:MacInstaller_6.png|none|border|400px]]
## [[Tutorial_on_setting_up_the_ardor_testnet|테스트넷을 운용 하고자 하시는 경우]] 옵션을 선택하세요. [[File:MacInstaller_7.png|none|border|400px]]
## 설치가 완료 되면, 종료 버튼을 클릭하세요. [[File:MacInstaller_9.png|none|border|400px]]
#애플리케이션에 있는 "ardor.app"을 클릭하시면 Ardor를 실행 하실 수 있습니다. 기존 계정을 보유하고 계신경우, 'Returning User'를 클릭 하셔서 로그인 하시면 됩니다. 새로 Ardor 계정을 생성하는데 도움이 필요하시다면, [[How_to_create_an_account_on_the_Ardor_Platform|신규 계정 만드는 법]]을 참조해 주세요.
</accordion>

<accordion parent="accordion" heading="===Linux===">

Here is the guide to installing the Ardor Client on a Linux 64-bit platform. 32-bit installation instructions are very similar; you just might need to download the 32-bit version of Java instead of the 64-bit one.
이 가이드는 Linux 64-bit를 기준으로 작성 되었습니다. 32-bit환경에서 설치가 필요 하신 경우 64-bit Java 대신 32-bit 버전 Java를 다운로드 하시면 됩니다.

하기 절차들은 Linux VPS 환경에서도 동일하게 적용 됩니다.

====Java 셋업====
이미 Java를 설치 하셨다면 이 단계를 건너 뛰시면 됩니다. 아직 설치 하지 않으셨다면, 귀하의 분배 저장소를 통해 하기와 같이 설치 하실 수 있습니다.(Ubuntu/Debian 빌드의 경우) :

<pre>sudo apt update
sudo apt install openjdk-11-jre-headless</pre>

`openjdk-8-jre-headless` 나 다른 Java 8+ 이상과 호환되는 버전을 사용 하실 수도 있습니다.

====Ardor 클라이언트 설치/실행====

=====Unix 설치파일 사용=====
Unix 설치파일인 [https://www.jelurida.com/ardor-client.sh ardor-client.sh]를 이용하면, 대부분의 리눅스 배포판과 호환되기 때문에 Linux 환경에서 사용 하실 수 있습니다.

<pre>wget https://www.jelurida.com/ardor-client.sh
sh ardor-client.sh
</pre>

=====유니버셜 Zip 패키지 사용=====
아래에 사용된 것처럼 좀 더 일반적인 지침을 따를 수 도 있습니다. :
# home 폴더로 이동 후 최신 클라이언트를 다운로드 합니다. ( {{NRSVersion}}버전):<br /><code>cd ~</code><br /><code>wget {{NRSDownload}}</code><code>wget https://www.jelurida.com/ardor-client.zip.asc</code> 그리고 파일의 설명이 올바른지 확인합니다. : <code>gpg --with-fingerprint ardor-client.zip.asc</code>
#Unzip it:<br /><code>unzip ardor-client.zip</code><br /><code>cd ardor</code>

=====Ardor 클라이언트 실행=====

#이제 소프트웨어를 실행하는 단계입니다. Ardor 디렉토리에서 <code>./run.sh</code> 이렇게 실행 하시거나, 백그라운드에서 실행 하시려면 <code>./run.sh --daemon</code> 와 같이 실행 하시면 됩니다. 창에 다음과 유사한 텍스트가 표시되면, 곧 서버가 활성화 됩니다. : <br/><code>Ardor server {{NRSVersion}} started successfully.</code> 이 쉘창은 Ardor 서버를 실행하면서 모든 Ardor 로그 메시지를 보여주기 때문에 계속 실행 하셔야 합니다!<br />
#Ardor 클라이언트에 접근 하시려면 웹브라우저를 열어 http://localhost:27876/ 를 실행하세요. 컴퓨터에서 Ardor를 처음 실행 하신경우, Ardor 블록체인을 최신화 할때 까지 다운로드 해야 합니다. 네트워크 연결 속도에 따라 이 작업은 몇 시간이 걸릴 수도 있습니다. Ardor 클라이언트는 블록체인 다운로드시 진행 상태 바를 표시 할 것입니다. [[How_to_create_an_account_on_the_Ardor_Platform|신규 Ardor 계정을 생성 하시려면 여기]]를 참조 하세요..
#*참고: 클라이언트를 전용 서버나 VPS에 설치하신 경우, "localhost"를 귀하의 Server/VPS IP로 변경하셔야 합니다.
</accordion>

<accordion parent="accordion" heading="===Raspberry Pi===">

Raspberry pi에 Ardor 클라이언트를 설치 하고자 하시는 경우 [https://medium.com/@mrv_89306/solar-powered-ardor-blockchain-node-aa680a976c50 태양광 패널로 작동하는 Ardor 클라이언트 만들기]를 참고 하십시오.
</accordion>

<accordion parent="accordion" heading="===Android===">
Android 환경에서 풀노드를 실행 하고자 하시는 경우, [[Android_Full_Node|Android Full Node 설치 가이드]]를 참조하십시오.
</accordion>

==='''도움이 필요하신가요?'''===
다운로드 하거나 개발과정 중에 도움이 필요하신가요? 4가지 채널을 통해 도움을 드리고 있습니다 : [https://ardornxt.slack.com Slack #helpdesk 채널], [https://ardorforum.org Ardor Forum], [[Faq|FAQ]], [https://desk.zoho.eu/portal/jelurida/home helpdesk]

==Lightweight 컨트랙트 관련 문서==
Lightweight 컨트랙트는 기존의 Ardor API들 위에 자동화 레이어를 개발 할 수 있는 프레임워크를 뜻합니다. 공식 문서에서 이 기능과 관련된 더 많은 정보를 확인해 보십시오. :

<div class="noprint" style="float:none; border:1px solid black;width:95%;background-color:#F6F0F0;padding:2px;">
{| cellspacing="0"
| style="padding-left:50px;"| '''[[Lightweight_Contracts|Lightweight 컨트랙트 관련 문서]]'''
|}</div>
<noinclude>

==Ardor 로그인==
계정을 생성하기 위해 Ardor에 로그인 하는 여러가지 방법이 있습니다. 이에 대한 설명은 [[Login_Page_Tutorial|로그인 페이지 튜토리얼]]에 있습니다.

==네트워크 사용을 위해 ARDR 얻는 법==

Ardor 클라이언트가 설치되었다면, 이제 첫 트랜잭션을 만들어 볼 차례입니다. 이렇게 하려면 ARDR, IGNIS 또는 다른 차일드 체인 토큰을 보유해야 합니다. Ardor 메인넷에 있는 토큰들은 실제 가치를 지닌 토큰들이며, 현재 많은 거래소를 통해 유통되고 있습니다.

앞으로 만나 볼 예제에서 만나볼 토큰들은 Testnet에서 사용하는 것들입니다. 이러한 토큰은 거래소에서 거래되지 않으며 금전적인 가치가 없습니다. Testnet에서의 토큰은 개발자/사용자가 기능을 실험해 볼수 있도록 편의를 위해 제공되고 있습니다.

Testnet 토큰을 수령하시려면 [https://ardorforum.org Ardor Forum]이나 [https://ardornxt.slack.com slack] #helpdesk 채널에 문의 또는 [https://www.ardor.world/faucet_ardor/ faucet] 에서 받으 실 수 있습니다.

=== 거래소 ===

* [https://www.jelurida.com/ardor/explorers 현재 ARDR이 거래되고 있는 거래소]

==다음 단계==

[[Basic_tutorials|기본 튜토리얼]]에서 Ardor의 기본적인 사용법을 확인 하시고, Ardor의 광법위한 빌트인된 [[Features|기능]]들을 알아 보세요.

=== 스테이킹 ===

Ardor에서 스테이킹(Staking) 하는 것은 [[Forging_(f)|포징(Forging)]]이라고 합니다. 1,000 ARDR 이상 가지고 계실 경우 포징을 하실 수 있으며, 귀하의 노드가 블록을 생성하게 되면 해당 블록내의 트랜잭션 수수료를 획득 하실 수 있습니다.

뿐만 아니라 퍼블릭 고정 IP를 이용해 API와 피어 포트를 개방하여 노드를 운영 하시면, [[Node_Reward_Program|노드 보상 프로그램]]에 참여 하실 수 있습니다.

==에러 피드백==

혹시 이 문서들에서 오류를 발견 하신다면, 수정 할 수 있도록 알려 주시면 감사하겠습니다. 문의 사항이 있으실 경우, [mailto:info@jelurida.com info@jelurida.com]로 연락 주시면 가능한 빨리 답변 드리도록 하겠습니다.

<accordion parent="accordion" heading="최근 문서 변경 및 업데이트 이력">
{{Special:SimpleChanges/days=150,limit=100,bots,hideminor,namespace=0}}
</accordion>

Lightweight Contracts/en

2020-08-11T00:38:55Z

FuzzyBot: Updating to match new version of source page

<languages />
{{#seo:
|title=Lightweight Contracts
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki, Lightweight Contracts
|description=Lightweight Contracts represent a framework for developing a layer of automation on top of the existing Ardor APIs.
}}
[[Category:Features]]

== Introduction to Lightweight Contracts ==
Lightweight Contracts represent a framework for developing a layer of automation on top of the existing Ardor APIs.

Contracts are developed by implementing predefined interfaces. The contract code is deployed to the blockchain as a cloud data transaction, which stores the code itself, and a contract reference transaction which associates a specific account with an existing deployed contract and configures the contract setup parameters for this specific account.

Learn more about the concepts behind the lightweight contracts using these resources:

[https://medium.com/coinmonks/lightweight-contracts-b738b6e29377 introduction article]

[https://medium.com/@lyaffe/lightweight-contracts-faq-30273120da9a frequently asked questions]

[[Basic_tutorials#Tutorial_Seminar_on_Turing-complete_Lightweight_Contracts| video seminar]]

== Prerequisites ==
Contract developers are expected to master the Java programming language or any other language which uses the Java JVM as its runtime environment.

Some prior knowledge of blockchain in general, Ardor specifically. Familiarity with concepts like account, passphrase, transaction, and block are important but not mandatory as you can always review the sample contracts supplied with the product as reference implementation.

== Getting Started ==

=== Installation ===

As of Ardor 2.2.3 when installing Ardor using the Windows or Mac installer a fully functional JDK is installed into the jdk folder under the product installation. We recommend that you use this JDK version when setting up your IntelliJ project. For all other configurations install Java SE JDK 8 or higher manually.

Install the latest version of the IntelliJ IDE, the free community edition is supported. You can develop contracts using any other Java IDE but the project setup and all examples assume using the IntelliJ IDE.

Install the latest version of Ardor and make sure to leave the dev.tools option checked during installation.

=== Contract Runner ===

Unlike many other contract development frameworks, lightweight contracts are not executed by every node on the blockchain, instead node operators have to configure their node to run contracts by registering the contract runner addon. The contract runner monitors every new block for trigger transactions. When found it triggers the respective contract after loading it from the blockchain. The contract runner also supports contracts which execute on every block and provides APIs for triggering contracts directly or using a transaction voucher.

==== Contract Runner fees and funds ====

The contract runner account needs funds to pay the fees for any submitted transaction.
Please ensure that the account has enough balance on every chain where the contracts
will submit transactions. Alternatively, you can setup a bundler to sponsor the fees
and let the contract runner submit zero fee transactions.

The contract runner uses the reference transaction mechanism to link any submitted
transaction to the transaction that triggered the contract. This ensures that
the confirmation of the new transaction depends on the confirmation of the triggering
transaction. This requires a '''deposit of 10 ARDR''' for every submitted transaction
that is refunded when both transactions are confirmed or the submitted transaction
expires. So please '''make sure the contract runner account has enough ARDR balance to cover this deposit'''.

==== How to configure the Contract Runner ====

First and foremost, to activate the contract runner for your node add the property <pre>nxt.addOns=nxt.addons.ContractRunner</pre> to your node's [[Faq#Node_configuration_using_the_nxt.properties|nxt.properties]] file.

You have now several ways to configure the contract runner. '''You only need to use one of the options.'''

* The easiest and recommended way is to use the [[Node_Processes_Configuration|Node Processes UI]] to set up an encrypted configuration file stored on the node. You only need to save the file once and then just start the file using an encryption password on each node start. The ''Save'' modal popup even creates a basic working configuration for you that is fully functional so most of the times it is just a matter of entering the passphrase and an encryption password and you are good to go.

[[file:Processes_SaveContractRunner.png|class=img-responsive|center|Save Contract Runner modal]]

* Another option is to keep the configuration on your local computer and upload it as a json file using the provided button on the contract runner status page accessible via the ''Settings'' menu.

* You can also add the configuration parameters directly on the [[Faq#Node_configuration_using_the_nxt.properties|nxt.properties]] file so they will be used right away as the node starts. '''You need to prefix every parameter''' with <code>addon.contractRunner.</code> so they become like this: <code>addon.contractRunner.secretPhrase=IWontTellYou</code> Please be aware that there are several parameters that shall remain secret like the accounts’ secret phrases or some contract setup parameters. The <code>nxt.properties</code> file is stored in clear text.

==== Contract Runner General Configuration Settings ====

The following properties control the Contract Runner execution.

'''"secretPhrase"''' - specify the secret phrase of the contract runner account i.e. the account from which the contract runner will submit transactions. This passphrase is never submitted to any remote node. Be careful if you decide to store this data in the ''nxt.properties'' file as it is stored in clear text.

'''"accountRS"''' - alternatively if you only want your contract runner to verify transactions submitted by another contract runner, specify the account of the contract runner you would like to follow. This way your contract runner can repeat the contract calculations and verify transactions submitted by another contract but not submit its own transactions.

'''"autoFeeRate"''' – if set to true (default: false), the contract runner will calculate the best fee available based on the current bundlers. This should be equivalent to the ''Calculate Fee'' button on the Wallet UI.

'''"minBundlerBalanceFXT"''' – this optional parameter allows filtering out bundlers when ''autoFeeRate'' is activated. Bundlers with an effective balance below the property ''minBundlerBalanceFXT'' are not considered for the best fee calculation. The default for this property is to use the same value as the global property ''nxt.minBundlerBalanceFXT''.

'''"minBundlerFeeLimitFQT"''' - this optional parameter allows filtering out bundlers when ''autoFeeRate'' is activated. Bundlers with a fee limit currently below the property ''minBundlerFeeLimitFQT'' are not considered for the best fee calculation. Again, the default for this property is to use the same value as the equivalent global property.

'''"feeRateNQTPerFXT.<Chain Name>"''' - when ''autoFeeRate'' is set to false or the best fee cannot be obtained the contract runner will use this value specified in NQT to calculate the child chain fee to submit. For each chain your contract runner is expected to submit transactions, you can specify a different value. Example: to set the rate to 2.5 IGNIS per ARDR, set this property to 250000000. i.e. 2.5 IGNIS specified in NQT.

'''"validator"''' - if set to true (default: false), the contract runner will watch for transactions submitted by other contract runners and will try to verify that the other contract runner indeed runs the contract stored on the blockchain.

'''"validatorSecretPhrase"''' - when ''validator'' is set to true, and another contract runner is using an account under account control, specify here the secret phrase of the controlling account. Your contract runner will intercept the transactions submitted by the other contract runner, repeat the calculations, and if it receives the same result, will submit an approval transaction for the transaction submitted by the other contract runner.

'''"catchUpInterval"''' - a timeout value specified in seconds (default: 3600 i.e. one hour). During blockchain download, the contract runner will only submit transactions when downloading a block with a timestamp later than the current time minus the defined ''catchUpInterval''. The purpose of this setting is to prevent a contract runner from flooding the unconfirmed transaction pool with duplicate transactions during blockchain download.

'''"seed"''' - supply random seed to the contract runner formatted as hex string (default: the public key of the contract account which is useless from randomness perspective). Convert any random value to hex string using the hexConvert API and specify the resulting hex string value as a seed. A seed of less than 16 bytes can be easily brute-forced so make sure your seed is longer. Keep your seed secret, it can be used in the future to validate your contract execution.

==== Contract Runner Contract Specific Settings ====

Note that in most cases there is no need to specify these parameters. Always prefer using contract setup parameters that are stored on the blockchain itself except when a contract parameter has to remain secret (for example, a passphrase or some secret credentials to a 3rd party service).

In the rare cases when this configuration is needed it is recommended to use the [[Node_Processes_Configuration|Node Processes UI]].

Alternatively, specify the configuration file used by the contract runner to load contract specific setup parameters by adding the property ''addon.contractRunner.configFile'' to ''nxt.properties'', for example <code>addon.contractRunner.configFile=./conf/contracts.json</code>, the specified path is relative to the [[faq#User directories per product and platform|user directory]].

A sample contract configuration file is provided in the ./addons/resources/contracts.json file under the installation folder. Copy this file to the conf folder under your project's [[faq#User directories per product and platform|user directory]] and configure it as follows.

'''"params"''' - specify contract setup parameters per contract. Use this setting only for private setup parameters that you don't like to submit to the blockchain such as passwords, API keys, etc. Otherwise specify the setup parameters in the contract reference transaction as explained in the contract manager configuration. The contract parameters configured in the params object are accessed by the contract code using the context method <syntaxhighlight lang="java">context.getContractRunnerConfigParams(getClass().getSimpleName())</syntaxhighlight>

Alternatively, create an inner interface decorated with the <code>@ContractParametersProvider</code> annotation inside your contract and define a method with the annotation <code>@ContractRunnerParameter</code> using the same name as the corresponding parameter in the contract runner configuration file.
For example see the <code>secretPhrases()</code> method of the <code>LeaseRenewal</code> sample contract which returns the array of passphrases specified in contracts.json

<code>{ "params": { "LeaseRenewal": { "secretPhrases": [ ... ] }}}</code>

==== Monitoring the contract runner ====

To verify that the contract runner has started, look for the message "ContractRunner Started" in the [[Faq#Where_to_find_the_node_log_file.3F|node log file]].

To check the status of the contract runner and deployed contracts, invoke the getSupportedContracts API.

In response, you'll receive an array of contracts supported by the specific contract runner and their properties, and the contractAccount parameter which specifies the owner account of the contract runner, which is based on the passphrase or account id you specified in the contract runner configuration.

In case the contract runner has failed to start, the getSupportedContracts API will return a descriptive error message.

As of version 2.2.1 when your wallet is connected to a contract runner node, you can choose "Contracts" from the "Settings" menu to view information about the contract runner and the deployed contracts. Including information about invocation parameters for the contracts and validation used by the contract.

[[file:Contracts.page.PNG|class=img-responsive|Contracts Page]]

=== Contract Manager ===

The contract manager is a command-line utility that manages the contract lifecycle. Its primary usage is to deploy contracts to the blockchain, use it also to add or change a reference to an existing contract, to update contract setup parameters, to remove old contract references, and to verify that a specific contract was compiled from a specific Java source file.

==== Contract Manager Configuration ====

The settings which control the operation of the contract manager are defined in the nxt.properties file, their documentation is specified in the ./conf/nxt-default.properties file under the installation folder in the "#### CONTRACT MANAGER ####" section.

You should define the secret phrase for transactions submitted by the contract manager using the property <code>contract.manager.secretPhrase=[Secret Phrase]</code>

The contract manager connects to an Ardor node to use the Ardor APIs and submit transactions. By default, it connects to a node running on localhost. Use the <code>contract.manager.serverAddress=[Server Address]</code> property to connect the contract manager to a remote node. The contract manager will never submit its passphrase to a remote node.

Use the optional <code>contract.manager.uploadParamsFile=[Path to configuration file]</code> property, to configure the contract manager upload parameters configuration file.

==== Upload Parameters Configuration File ====

The upload parameters file contains a json array of contract definitions named "contracts".

Note: as of version 2.2, the contract upload configuration file is optional. Every setting in this file can be configured using a matching property in nxt.properties file.

For each contract specify the following parameters:

'''"className"''': the name of the class without package name, this name represents the class name loaded by the contract runner from the [[Data_Cloud|data cloud]] and the name of the contract reference.

'''"packageName"''': [optional, default to package specified as command line parameter] the Java package name of the contract class as specified in the package directive inside the source code.

'''"filePath"''': only in case the contract is deployed as a Jar file. Specify the path to the Jar file which will be deployed to the cloud data. If no filePath is specified the contract manager will attempt to load the class file specified by the className attribute from the classpath.

'''"params"''': a Json object representing the contract setup parameters. These parameters are accessed by the contract through its context object or using the <code>@ContractParametersProvider</code> interface methods decorated with <code>@ContractSetupParameter</code> annotation.

The upload parameters for the sample contracts available out of the box are defined in the ./addons/resources/contract.uploader.json file under the installation folder. This file is automatically copied to the ./conf folder under the user directory in case it does not exist yet.

Alternatively, every setting in the contract uploader file can be defined in nxt.properties using the following format:

Contract Manager settings for a specific contract - contract.[contractName].[setting]

Contract setup parameters submitted to the blockchain - contract.[contractName].param.[setting]

For example, to define the "frequency" setup parameter of the "AllForOnePayment" contract use the following property:

<code>contract.AllForOnePayment.param.frequency=6</code>

== Setting Up the Development Environment ==

Assuming all dependencies were installed, we can now open the Ardor contracts project inside IntelliJ and start developing contracts.

The IntelliJ project structure is provided as part of the "Contract Development Tools" package you selected when installing Ardor so there is no need to create a new project.

If you installed Ardor into a read-only folder you will need to copy it to a folder for which you have write permissions.

Windows - copy <code>"c:\Program Files\Ardor"</code> to a writable location such as <code>c:\Users\<Your user>\Documents</code>

Mac - copy <code>/Applications/ardor.app</code> to <code>ardor.app</code> in your home folder (use cp -R from the terminal for recursive copy on Mac)

Linux - this should not be an issue as long as you installed Ardor into a folder you own.

Alternatively, if you decided to develop your project in the same location where you installed Ardor, a future upgrade may override some of the project files so make a backup of your project before upgrading.

Start IntelliJ, from the top menu choose "File->Open", in the resulting "Open file or project" dialog select the Ardor folder itself.

[[File:ope.project.PNG|class=img-responsive]]

Select the Ardor module from the left pane by clicking the "1:Project" label.

[[File:project1.PNG|class=img-responsive]]
[[File:project2.PNG|class=img-responsive]]

The Ardor module contains the sample contracts provided with installation.

Open the Ardor module settings by pressing F4 while the module itself is in focus or right click and choose "Open Module Settings".

Select the "Project" link from the left pane and set the "Project SDK" to the Java JDK you installed earlier and set the "Project Language Level" to 8 and click "Ok".

[[File:project5.png|class=img-responsive|border|Project structure]]

Build the Ardor module by selecting the "rebuild Module 'Ardor'" from the IntelliJ "Build" menu (Ctrl+Shift+F9)

Restart IntelliJ and reopen the project.

Under the Ardor module, there are two Java source roots, the first contains the sample contracts, the second contains the unit tests for the sample contracts.

For example, this is the HelloWorld sample contract.

[[File:project4.PNG|class=img-responsive|HelloWorld sample]]

Your IntelliJ contracts project contains the following launchers, visible in the selection box on the top right.

<code>Ardor Local</code> - runs the node using the existing node configuration

<code>ContractRunnerSuite</code> - invokes the automatic tests for all contracts

You are now ready to develop your first contract

== Contract Development ==

A contract is composed of one or more Java class files possibly packaged into a Jar and possibly relying on other Jar files.

The main contract class has to extend the nxt.addons.AbstractContract class and implement one or more of the provided callback methods which are invoked by the Contract Runner in response to specific events as shown as follows:

{{TransactionTriggers}}

A contract should implement one or more of these callback methods.

=== Context Objects ===

Each of the above callback methods, receive a context object, the context object provides various services to the contract and represents the interface between the contract and the blockchain.

Always prefer using the context object over calling directly to an internal blockchain method since every method provided by the context is guaranteed to maintain backward compatibility and not break your contract code when a new Ardor release is deployed. The services provided by the context object depend on the type of callback, these services are documented in the [https://testardor.jelurida.com/doc/ Javadoc] for the context class.

=== API callers ===

For each of the Ardor public APIs there is a specific Java caller class named the same as the API with a capital letter at the beginning and a "Call" prefix.

For example the call object for the getBlockchainStatus API is <code>GetBlockchainStatusCall</code>.

API invocation always follows the same pattern, create a caller instance, possibly set some API parameters, then invoke the call() method to receive a Json response as a JO object you can then work with.

For example: to invoke the getExecutedTransactions API from inside the contract:

<syntaxhighlight lang="java">
GetExecutedTransactionsCall request = GetExecutedTransactionsCall.create(2).height(height).type(0).subtype(0).recipient(context.getConfig().getAccount());

JO getExecutedTransactionsResponse = request.call();
</syntaxhighlight>

Always use the API callers to access information stored on the blockchain since these API callers represent the interface between your contract and the data stored on the blockchain. The API callers will remain compatible in future releases.

=== Submitting Transactions ===

In most cases, contracts should not save any internal state between contract invocations. To make changes to the blockchain state, contracts should submit transactions. To submit a transaction, invoke the API caller for the specific transaction type, then use the <code>context.createTransaction()</code> method to submit the transaction to the blockchain.
Internally the createTransaction method implements local signing, fee calculation, and other complex processing that you as contract developer don't have to deal with.

Example:

<syntaxhighlight lang="java">
SendMoneyCall sendMoneyCall = SendMoneyCall.create(context.getChainOfTransaction().getId()).recipient(recipient).amountNQT(returnAmount);

context.createTransaction(sendMoneyCall);
</syntaxhighlight>

=== Contract Parameters ===

For contracts triggered by a transaction use <syntaxhighlight lang="java">context.getRuntimeParams()</syntaxhighlight> to load the specific invocation parameters or preferably define the parameter as a method of an inner interface decorated with @ContractParametersProvider annotation. Name the method the same as the parameter name and decorate it with the @ContractInvocationParameter annotation.

To load the contract setup parameters specified in the contract reference transaction use <syntaxhighlight lang="java">context.getContractSetupParameters()</syntaxhighlight> or preferably define the parameter as a method of an inner interface decorated with @ContractParametersProvider annotation. Name the method the same as the parameter name and decorate it with the @ContractSetupParameter annotation.

To load the contract runner parameters specified in the contract runner configuration file for the specific contract use <syntaxhighlight lang="java">context.getContractRunnerConfigParams(getClass().getSimpleName())</syntaxhighlight> or preferably define the parameter as a method of an inner interface decorated with @ContractParametersProvider annotation. Name the method the same as the parameter name and decorate it with the @ContractRunnerParameter annotation.

All the parameters getter methods return a JO object.

For usage example of the <code>@ContractParametersProvider</code> decorated inner interface see the <code>HelloWorldForwarder</code> and <code>LeaseRenewal</code> sample contracts.

=== Working with Json ===

All API callers and configuration parameters return a JO object which represents a Json object.

Use the JO object to query the Json object. Specifically use the getArray() method to obtain a JA object representing a Json Array.

There are plenty of usage examples in the sample contracts.

=== Accessing External Resources ===

Unlike most smart contract frameworks, lightweight contracts support access to external resources. Your contract can communicate as client of any external service which provides a Java client API library, or Http, XML, Json, Soap, ldap, or a similar interface.

If necessary your contract can access code from 3rd party Jar files as long as these Jar files are included in the classpath of the contract runner node. You may add external Jar files to the classpath of the node by copying the files to the ./addons/lib folder under the installation folder.

Learn mode about [https://medium.com/@lyaffe/oracle-contracts-on-ardor-94480bc4890b Oracle Contracts]

=== Lightweight Contracts Design ===

To learn more about the internal design of the lightweight contracts framework see [https://medium.com/@lyaffe/lightweight-contracts-design-f37fa5211bae this article]

== Best Practices ==

=== Single Source File Multiple Classes ===

To simplify contract development always attempt to concentrate all your source code into a single source file which defines the contract class itself and possibly additional inner classes. When deploying the contract to the blockchain the contract manager loads the main contract class and checks if it has inner classes. If there are no inner classes, the contract class file is deployed to the blockchain, otherwise, the contract manager packs the contract and all its inner classes into a Jar file and deploys the Jar file to the blockchain.

=== Parameter Validation ===

Always start your contract code with input validity checks. For example, if your contract is triggered by a sendMoney transaction, make sure the payment recipient is the contract account and that the payment uses the expected chain, that the payment amount is correct, etc.

Validate that all invocation parameters represent the data type you expect and are within their valid boundaries.

For your convenience you can decorate the contract <code>processTransaction</code> and <code>processVoucher</code> methods with one of the following predefined annotations:

<code>@ValidateTransactionType</code> validates that the trigger transaction type is of one of the accepted types and is not of one of the rejected types.

<code>@ValidateContractRunnerIsRecipient</code> validates that the contract runner account is the recipient of the trigger transaction.

<code>@ValidateChain</code> validates that the chain of the trigger transaction is one of the accepted chains and is not one of the excluded chains.

See usage example in the <code>RandomPayment</code> contract.

=== Stateless Contracts ===

In most cases, contracts should only store state information in the blockchain itself or as setup parameters. If you are using member variables in the contract class itself you might be doing something wrong. Bare in mind that the contract runner may restart at any moment and that your contract callbacks may execute in parallel with other contracts. Learn more about [https://medium.com/coinmonks/stateful-vs-stateless-blockchain-contracts-bcd1b0c25ff stateless contracts]

=== Internal Blockchain Functionality ===

Do not invoke public methods of the blockchain directly. Always attempt to use the context object and the caller APIs.

If you are missing some essential function or service, let us know and we will add it in the next release.

=== Random Data ===

If your contract requires random data, make sure to define a secret random seed in the contract runner configuration. See the following article about our approach to [https://hackernoon.com/random-number-generator-in-contracts-44abfe48240d random number generation]

== Contract Deployment ==

As explained above, contract deployment is a two-step process, first the contract code is deployed using a cloud data transaction then a contract reference transaction is submitted to provide an entry point to the correct version of the contract. While this deployment process can be accomplished manually using the Ardor APIs, it is much simpler to perform the deployment using the contract manager utility.

First [[#Contract Manager|configure the contract manager]] then use either the contract manager IntelliJ plugin (recommended) or invoke the command line utility (ContractManager.bat or contractManager.sh) from the command line to view the available options.

In both configurations, the contract manager connects to an existing full node, preferably running on your local workstation. Make sure your node is properly configured and fully synchronized with the blockchain.

Remember that the contract manager deploys transactions to the blockchain. For the transactions to confirm you need to wait for the next block.

=== Contract Manager IntelliJ Plugin ===

The contract manager plugin provides a simple configuration dialog to invoke the contract manager utility from inside the IntelliJ IDE. You first need to install the contract manager plugin into your IDE, this process has to be repeated after every Ardor version upgrade.

==== Install the Plugin ====

From the "File" menu choose the "Settings" option.

From the resulting "Settings" dialog select the plugins page.

===== IntelliJ 2018.3 and higher =====

[[File:plugin11.png|class=img-responsive|Settings]]

Select the cogwheel menu on the right and click "Install plugin from disk" menu item. Using the resulting file dialog select the ContractManagerPlugin.zip file from the Ardor installation folder.

===== IntelliJ 2018.2 and lower =====

[[File:plugin1.png|class=img-responsive|Settings]]

Click the "Install plugin from disk" button at the bottom. Using the resulting file dialog select the ContractManagerPlugin.zip file from the Ardor installation folder.

[[File:plugin2.png|class=img-responsive]]

You should now see an "Ardor Contract Manager" entry listed in the plugins list.

Restart IntelliJ to complete the installation.

The contract manager plugin is now installed.

Repeat this process whenever you upgrade Ardor to install a new version of the plugin.

==== Use the Plugin ====

To use the contract manager plugin you must first start your Ardor node. One simple way to do so is to run the node using the "Ardor Local" launcher from inside the IntelliJ IDE. If your node is offline while running the contract manager, the contract manager will display the message "Cannot connect to http://<address>:<port>/nxt make sure the node is running" and terminate.

Edit the runtime configurations.

[[File:plugin4a.png|class=img-responsive]]

Add a new configuration of type "Ardor Contract Manager"

[[File:plugin5.png|class=img-responsive|Ardor Contract Manager]]

Name the configuration and define the contract manager options

[[File:plugin6.png|class=img-responsive|border|Contract Manager Options]]

Run the configuration as usual

[[File:plugin7.png|class=img-responsive]]

Review diagnostic messages logged to the IntelliJ console at the bottom of the screen.

=== Contract Manager Command Line Utility ===

==== Examples ====

Deploy a new version of the ForgingReward contract:

<syntaxhighlight lang="bash">contractManager.bat -u -n ForgingReward -p com.jelurida.ardor.contracts</syntaxhighlight>

Response:

<pre>
...

Contract class com.jelurida.ardor.contracts.ForgingReward uploaded 5f4afbead4f7f887082a36dd97df72f6ed7f980c1b3e99eccb7d67bb150c9748
...

Contract reference registered ForgingReward={"rewardArdor":"true","interval":5,"rewardNxt":"true","rewardChain":"IGNIS","rewardAmountNQT":150000000} for contract chain: IGNIS, full hash: 5f4afbead4f7f887082a36dd97df72f6ed7f980c1b3e99eccb7d67bb150c9748
</pre>

List deployed contracts for a specific account:

<syntaxhighlight lang="bash">contractManager.bat -l -a ARDOR-XK4R-7VJU-6EQG-7R335</syntaxhighlight>

Response:

<syntaxhighlight lang="json">
{"contract":{"chain":2,"transactionFullHash":"ff374385044519900147c145beeaa07520f0a9850b95d84b835c88ff1ce81015"},"name":"DistributedRandomNumberGenerator","id":"10806939862175194746","params":"{}"}

{"contract":{"chain":2,"transactionFullHash":"5f4afbead4f7f887082a36dd97df72f6ed7f980c1b3e99eccb7d67bb150c9748"},"name":"ForgingReward","id":"10360831005888949167","params":"{\"rewardArdor\":\"true\",\"interval\":5,\"rewardNxt\":\"true\",\"rewardChain\":\"IGNIS\",\"rewardAmountNQT\":150000000}"}

{"contract":{"chain":2,"transactionFullHash":"8292a5e3a9bd209a85b3a865be8175d1c762393dac33e84a3113e19a7efc0e39"},"name":"NewAccountFaucet","id":"4615352619232966745","params":"{\"thresholdAmountNQT\":72000000000,\"chain\":2,\"thresholdBlocks\":1440,\"faucetAmountNQT\":500000000}"}
</syntaxhighlight>

Delete contract reference for a specific account (the contract itself is not deleted)

<syntaxhighlight lang="bash">contractManager.bat -d -a ARDOR-XK4R-7VJU-6EQG-7R335 -n ForgingReward</syntaxhighlight>

Response:

<pre>
Contract reference 10360831005888949167 deleted for account ARDOR-XK4R-7VJU-6EQG-7R335 contract name ForgingReward
</pre>

Add or update contract reference

<syntaxhighlight lang="bash">contractManager.bat -r -h 5f4afbead4f7f887082a36dd97df72f6ed7f980c1b3e99eccb7d67bb150c9748 -n ForgingReward</syntaxhighlight>

(the hash parameter -h is the full hash of the cloud data transaction storing the contract version you would like to reference)

Response:

<pre>
Contract reference registered ForgingReward={"rewardArdor":"true","interval":5,"rewardNxt":"true","rewardChain":"IGNIS","rewardAmountNQT":150000000} for contract chain: IGNIS, full hash: 5f4afbead4f7f887082a36dd97df72f6ed7f980c1b3e99eccb7d67bb150c9748
</pre>

Verify that a contract class in the blockchain was compiled from a specific source file, note that this action has to run using a Java JDK and not using the Java JRE provided with some of the installations.

Invoke the command below from the Ardor installation directory. The verification action has to run using an Oracle Java JDK.

<pre>
"c:\Program Files\Java\jdk-10.0.2\bin\java.exe" -Djava.security.manager -Djava.security.policy=contractManager.policy -cp classes;lib\*;conf nxt.tools.ContractManager -v -h 4a8cd1c3fc86ad1cfbce4957142ff86c5d908af633bc6e38fddbf0be2418ff05 -s c:\Users\liory\ardor\addons\src\java\com\jelurida\ardor\contracts\HelloWorld.java
</pre>

Response:

<pre>
Verification succeeded - class files are identical
</pre>

== Contract Security ==

The contract runner relies on the Java JAAS framework to ensure that malicious contracts downloaded from the blockchain cannot attack the contract runner local workstation or the blockchain node operations. To achieve this, contracts are loaded using their own class loader and run in their own protection domain which forms a sandbox that limits the permissions assigned to contract code.

Most contracts should be able to run using default the permissions. However, if you need to make changes to security permissions, read on.

The main configuration files for controlling the contract security are ardor.policy and ardordesktop.policy, both files are standard [https://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html Java policy files]. ardor.policy is the active policy file when running in command line mode and when running unit tests. ardordesktop.policy is a slightly more permissive policy file active when running the desktop wallet. In this document, we will always use ardor.policy, everything explained is also applicable to ardordesktop.policy.

By default, contracts are assigned the permissions defined in the virtual untrustedContractCode protection domain.

<syntaxhighlight lang="java">
grant codeBase "file://untrustedContractCode" {
permission java.io.FilePermission "${java.io.tmpdir}*", "read,write,delete";
permission java.util.PropertyPermission "java.io.tmpdir", "read";
};
</syntaxhighlight>

The defined permissions grant the contract code access to the temporary folder on the contract runner workstation. The contract can freely read, write, delete files in this folder.

In addition, contracts are always allowed to connect to any internet address.

See the <code>AllowedActions</code> contract for code samples permitted by the policy file and the <code>ForbiddenActions</code> for code samples not permitted by default. Neither of these samples cover the full list of permitted and non-permitted actions.

=== Granting Additional Contract Permissions ===

At the moment all sample contracts are designed to run using the default untrusted contract permissions, however, developing contracts with elevated permissions is supported. A contract runner node operator can grant additional permissions by adding these permissions to the untrustedContractCode protection domain of ardor.policy, but this is discouraged since it will grant these permissions to all the contracts run by this contract runner. Instead, we recommend elevating permissions per contract signer account or per specific contract.

To grant additional permissions for contracts signed by a specific account, define the public key of the account that submitted the contract to the blockchain, in a new protection domain entry using the "signedBy" token. The public key should be specified in hex string format.

For example the following ardor.policy section grants additional permissions for contracts submitted to the blockchain by the account whose public key is the following:<pre>112e0c5748b5ea610a44a09b1ad0d2bddc945a6ef5edc7551b80576249ba585b</pre>

<syntaxhighlight lang="java">
grant codeBase "file://untrustedContractCode" signedBy "112e0c5748b5ea610a44a09b1ad0d2bddc945a6ef5edc7551b80576249ba585b" {
permission nxt.util.security.BlockchainPermission "db";
permission nxt.util.security.BlockchainPermission "getBlockchain";
};
</syntaxhighlight>

Similarly to grant additional permissions to a specific contract use the "principal nxt.util.security.TransactionPrincipal" setting followed by the contract's transaction full hash or the hash of the whole tagged data as saved in the blockchain or the hash of the contract class/jar itself.

<syntaxhighlight lang="java">
grant codeBase "file://untrustedContractCode" principal nxt.util.security.TransactionPrincipal "df15278b53c5c24ccb179302834608b50b94c3e91c97ffa0510357e35fec919b" {
permission nxt.util.security.BlockchainPermission "db";
};
</syntaxhighlight>

To monitor the permissions assigned to your contract in runtime, use the following Java command line flag <code>-Djava.security.debug="access"</code>. Additional information about protection domains can be obtained using <code>-Djava.security.debug="access,domain"</code> but this creates very verbose output.
Look in the generated log for permissions which are marked as "denied" and use the diagnostic information to learn the reason for denial.

To configure the ardor.policy file you can use any text editor or IntelliJ IDE but be warned that the syntax of this file is very strict, therefore every small typo will render the file useless and remove all permissions to all code resulting in errors when starting the node.

Alternatively use the graphical [https://docs.oracle.com/javase/tutorial/security/tour1/wstep1.html policytool] provided with the Java JRE for making changes to the policy file without the risk of creating syntax errors.

To temporarily disable all permission checks add the following property to the nxt.properties file:
<code>nxt.disableSecurityPolicy=true</code>

=== Checking Contract Permissions ===

A contract that requires elevated permissions from the contract runner should start by checking that these permissions were granted, if not, it should fail gracefully. Use the <code>context.isPermissionGranted()</code> API to check if a specific permission is granted. See the DatabaseAccess sample contract for example how to check for permissions. If a required permission is not granted, log an error message and return.

== Sample Contracts ==

There are multiple sample contracts included with source code as part of the product installation. The sample contracts are documented using javadoc and internal comments. Always use the sample contracts as reference to understand correct coding techniques and best practices.

[https://testardor.jelurida.com/doc/com/jelurida/ardor/contracts/package-summary.html ''Javadoc documentation'']

In the next sub-sections it will be explained several sample contracts. All the examples can be found in the [https://bitbucket.org/Jelurida/ardor/src/master/addons/test/java/com/jelurida/ardor/contracts/ contracts folder of the official repository].

=== Trading bot (CoinExchangeTradingBot.java) ===

Trading bot <code>CoinExchangeTradingBot.java</code> is a contract which performs market making on the coin exchange and asset exchange. Contract runners can define the holdings (coin or asset) on which to submit buy and sell orders and the percentage difference from a base exchange rate loaded from coinmarketcap, which serves as a sample data source. The bot can be configured to compete with other traders or issue orders according to the base exchange rate to provider liquidity.

=== Account Balance Notifier (AccountBalanceNotifier.java) ===

The account balance notifier <code>AccountBalanceNotifier.java</code> monitors the account balances of configured holdings and raises an alert in case their holding balance drops below some minimum limit. The notifier can be used to monitor an account performing market making to alert the operator in case a holding balance is exhausted.

=== Chain Monitor Contract (ChainMonitor.java) ===

The chain monitor contract <code>ChainMonitor.java</code> monitors specific aspects of the blockchain operations. It submits an alert to one or more notification services in case a problem with the blockchain operation is detected.

=== Notification service contracts (SlackNotifier.java, TelegramNotifier) ===

Notification service contracts <code>SlackNotifier.java, TelegramNotifier</code> are utility contracts used for posting messages from other contracts to Slack and Telegram respectively.

== Contract Trigger Transaction ==

To trigger the execution of a deployed contract, any account can submit a transaction with a special message attachment. The message should be prunable (leave "Message is Never Deleted" unchecked in the wallet) and should be formatted as Json, can be either encrypted or plain text, should identify the contract to execute and optionally provide contract specific invocation parameters.

=== Examples ===

Trigger the HelloWorld contract by sending a message transaction to the contract runner account with the text:

<code>{“contract”:”HelloWorld”}</code>

Trigger the SplitPayment contract and describe how to split the payment, by sending a payment transaction to the contract and add the following attached message:

<code>{"contract":"SplitPayment","params":{"ARDOR-SZKV-J8TH-GSM9-9LKV6":"0.2","ARDOR-9KZM-KNYY-QBXZ-5TD8V":"0.5","ARDOR-E93F-7E8Z-BHJ8-A65RG":"0.3"}}</code>

Note that the "params" token in the message is a Json object by itself, the data in the params object is contract specific. Consult the contract author as to which params need to be submitted and in which format.

When a trigger transaction is submitted, all active contract runners will process this transaction. Whether or not the contract will actually process the transaction depends on the contract itself.

For example, most contracts will only process payments submitted to their contract runner account and ignore payments made to other accounts but this depends on the contract logic. Contracts can choose to process certain transaction types, certain chains, and certain recipient accounts based on their own internal logic.

== Oracle Contracts - Interface with External Systems ==

One of the powerful features of Lightweight Contracts is their ability to interface with external systems to load data and register it on the blockchain and to save data to an external system based on blockchain data. Interfacing with external systems is a trade-off between decentralization and utility. There are cases where a specific contract runner can load data from an external system such as exchange rate or personal data that no other contract runner can validate. There is no choice for users but to trust the contract runner not to manipulate this data the same way users trust a centralized system. Still, once the data is registered on the blockchain, it is digitally signed and timestamped by the contract runner account and can no longer change. So as long as the contract runner is a trusted entity information provided by it can be used safely.

However, there are few steps contract developers need to take to increase the reliability of Oracle contracts, as a developer, you should consider that contracts should be designed to be idempotent (i.e. can run multiple times on the same data and produce the same result). For example, a contract can run once when a trigger transaction is received, then again if the node switches to a better fork and the trigger transaction is included in a different fork, and again in case the contract runner is re-downloading the blockchain. Ideally, in all these cases the contract should reproduce the exact same output transactions. The blockchain itself protects against including duplicate transactions in the blockchain.

However, when relying on external data there is no way to guarantee that transaction data won't change between invocations. Therefore developers of Oracle contracts should always look for duplicate transactions generated by the contract based on the same trigger transaction but with different data (if the data is the same, duplicate transactions will be discarded by the blockchain itself).

Contract developers need to override the following method:

<code>public <T extends TransactionResponse> boolean isDuplicate(T myTransaction, List<T> existingUnconfirmedTransactions) { ... }</code>

The method accepts the transaction currently submitted by the contract and a list of transactions already waiting to be included in the blockchain. The contract should implement contract specific policy to identify if the new transaction duplicates an existing transaction. If it does, the method should return true value to instruct the contract runner not to submit the new transaction to the blockchain.

Example for Oracle contracts

The <code>IgnisArdorRates</code> contract uses the Bittrex exchange APIs to calculate the market rate between Ardor and Ignis and compare it to the decentralized coin exchange market rate. For this contract duplicates are no a real risk, at worst, there will be slightly different exchange rates registered on the blockchain on the same block.

The <code>LiberlandCitizenRegistry</code> contract uses the Liberland APIs to load citizen data. There is a small risk that the citizen data will change between invocations of this contract so a duplicate check makes sense before submitting a transaction.

== Testing and Debugging your Contracts ==

Testing and debugging your contract is supported by the IntelliJ IDE using the standard tools used to test and debug any Java program.

=== Unit Tests ===

For each of the sample contracts provided with the product, there is also a matching unit test class with the same name followed by a "Test" postfix. For example contract <code>HelloWorld</code> has a unit test named <code>HelloWorldTest</code>.
Unit tests rely on the junit framework, each unit test starts from a clean blockchain copy, which only includes the Genesis block, it then deploys a contract, perform some actions on the contract and tests the output transactions.

All sample unit tests are grouped into the ContractRunnerSuite, the IntelliJ project provided by the installation includes a predefined launcher which runs this test suite. The first run will generate the unit tests blockchain database. Subsequent runs should work faster.

Our recommendation is that whenever you design a new contract you always design a matching unit test class to test it. Whenever you make changes to the contract make sure that all unit tests for the contract pass without errors. Unit tests also enable you to design your contract without deploying it to the blockchain where it is visible to others.

=== Debugging your Contracts ===

You can easily debug your contracts by placing a breakpoint inside the contract code. You can then run the unit test which test your contract in debug mode and debug the contract. Another option is to deploy your contract to the testnet then run your node using the "Ardor Local" launcher in debug mode. This will let you debug your contract exactly as it is executed in runtime. Since contracts are simply Java programs you can use any common debugging technique available by IntelliJ such as conditional breakpoints etc.

=== Obtaining more Diagnostic information ===

The contract runner and the contracts it runs, log information about their operation in the normal Ardor log.

Translations:Lightweight Contracts/254/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

Our recommendation is that whenever you design a new contract you always design a matching unit test class to test it. Whenever you make changes to the contract make sure that all unit tests for the contract pass without errors. Unit tests also enable you to design your contract without deploying it to the blockchain where it is visible to others.

Translations:Lightweight Contracts/252/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

For each of the sample contracts provided with the product, there is also a matching unit test class with the same name followed by a "Test" postfix. For example contract <code>HelloWorld</code> has a unit test named <code>HelloWorldTest</code>.
Unit tests rely on the junit framework, each unit test starts from a clean blockchain copy, which only includes the Genesis block, it then deploys a contract, perform some actions on the contract and tests the output transactions.

Translations:Lightweight Contracts/242/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

However, when relying on external data there is no way to guarantee that transaction data won't change between invocations. Therefore developers of Oracle contracts should always look for duplicate transactions generated by the contract based on the same trigger transaction but with different data (if the data is the same, duplicate transactions will be discarded by the blockchain itself).

Translations:Lightweight Contracts/241/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

However, there are few steps contract developers need to take to increase the reliability of Oracle contracts, as a developer, you should consider that contracts should be designed to be idempotent (i.e. can run multiple times on the same data and produce the same result). For example, a contract can run once when a trigger transaction is received, then again if the node switches to a better fork and the trigger transaction is included in a different fork, and again in case the contract runner is re-downloading the blockchain. Ideally, in all these cases the contract should reproduce the exact same output transactions. The blockchain itself protects against including duplicate transactions in the blockchain.

Translations:Lightweight Contracts/240/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

One of the powerful features of Lightweight Contracts is their ability to interface with external systems to load data and register it on the blockchain and to save data to an external system based on blockchain data. Interfacing with external systems is a trade-off between decentralization and utility. There are cases where a specific contract runner can load data from an external system such as exchange rate or personal data that no other contract runner can validate. There is no choice for users but to trust the contract runner not to manipulate this data the same way users trust a centralized system. Still, once the data is registered on the blockchain, it is digitally signed and timestamped by the contract runner account and can no longer change. So as long as the contract runner is a trusted entity information provided by it can be used safely.

Translations:Lightweight Contracts/238/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

For example, most contracts will only process payments submitted to their contract runner account and ignore payments made to other accounts but this depends on the contract logic. Contracts can choose to process certain transaction types, certain chains, and certain recipient accounts based on their own internal logic.

Translations:Lightweight Contracts/236/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

Note that the "params" token in the message is a Json object by itself, the data in the params object is contract specific. Consult the contract author as to which params need to be submitted and in which format.

Translations:Lightweight Contracts/230/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

To trigger the execution of a deployed contract, any account can submit a transaction with a special message attachment. The message should be prunable (leave "Message is Never Deleted" unchecked in the wallet) and should be formatted as Json, can be either encrypted or plain text, should identify the contract to execute and optionally provide contract specific invocation parameters.

Translations:Lightweight Contracts/280/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

Notification service contracts <code>SlackNotifier.java, TelegramNotifier</code> are utility contracts used for posting messages from other contracts to Slack and Telegram respectively.

Translations:Lightweight Contracts/279/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

=== Notification service contracts (SlackNotifier.java, TelegramNotifier) ===

Translations:Lightweight Contracts/278/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

The chain monitor contract <code>ChainMonitor.java</code> monitors specific aspects of the blockchain operations. It submits an alert to one or more notification services in case a problem with the blockchain operation is detected.

Translations:Lightweight Contracts/277/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

=== Chain Monitor Contract (ChainMonitor.java) ===

Translations:Lightweight Contracts/276/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

The account balance notifier <code>AccountBalanceNotifier.java</code> monitors the account balances of configured holdings and raises an alert in case their holding balance drops below some minimum limit. The notifier can be used to monitor an account performing market making to alert the operator in case a holding balance is exhausted.

Translations:Lightweight Contracts/275/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

=== Account Balance Notifier (AccountBalanceNotifier.java) ===

Translations:Lightweight Contracts/274/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

Trading bot <code>CoinExchangeTradingBot.java</code> is a contract which performs market making on the coin exchange and asset exchange. Contract runners can define the holdings (coin or asset) on which to submit buy and sell orders and the percentage difference from a base exchange rate loaded from coinmarketcap, which serves as a sample data source. The bot can be configured to compete with other traders or issue orders according to the base exchange rate to provider liquidity.

Translations:Lightweight Contracts/273/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

=== Trading bot (CoinExchangeTradingBot.java) ===

Translations:Lightweight Contracts/272/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

In the next sub-sections it will be explained several sample contracts. All the examples can be found in the [https://bitbucket.org/Jelurida/ardor/src/master/addons/test/java/com/jelurida/ardor/contracts/ contracts folder of the official repository].

Translations:Lightweight Contracts/225/en

2020-08-11T00:38:24Z

FuzzyBot: Importing a new version from external source

A contract that requires elevated permissions from the contract runner should start by checking that these permissions were granted, if not, it should fail gracefully. Use the <code>context.isPermissionGranted()</code> API to check if a specific permission is granted. See the DatabaseAccess sample contract for example how to check for permissions. If a required permission is not granted, log an error message and return.

Translations:Lightweight Contracts/214/en

2020-08-11T00:38:23Z

FuzzyBot: Importing a new version from external source

At the moment all sample contracts are designed to run using the default untrusted contract permissions, however, developing contracts with elevated permissions is supported. A contract runner node operator can grant additional permissions by adding these permissions to the untrustedContractCode protection domain of ardor.policy, but this is discouraged since it will grant these permissions to all the contracts run by this contract runner. Instead, we recommend elevating permissions per contract signer account or per specific contract.

Translations:Lightweight Contracts/211/en

2020-08-11T00:38:23Z

FuzzyBot: Importing a new version from external source

In addition, contracts are always allowed to connect to any internet address.

Translations:Lightweight Contracts/210/en

2020-08-11T00:38:23Z

FuzzyBot: Importing a new version from external source

The defined permissions grant the contract code access to the temporary folder on the contract runner workstation. The contract can freely read, write, delete files in this folder.

Translations:Lightweight Contracts/208/en

2020-08-11T00:38:23Z

FuzzyBot: Importing a new version from external source

By default, contracts are assigned the permissions defined in the virtual untrustedContractCode protection domain.

Translations:Lightweight Contracts/207/en

2020-08-11T00:38:23Z

FuzzyBot: Importing a new version from external source

The main configuration files for controlling the contract security are ardor.policy and ardordesktop.policy, both files are standard [https://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html Java policy files]. ardor.policy is the active policy file when running in command line mode and when running unit tests. ardordesktop.policy is a slightly more permissive policy file active when running the desktop wallet. In this document, we will always use ardor.policy, everything explained is also applicable to ardordesktop.policy.

Translations:Lightweight Contracts/206/en

2020-08-11T00:38:23Z

FuzzyBot: Importing a new version from external source

Most contracts should be able to run using default the permissions. However, if you need to make changes to security permissions, read on.

Translations:Lightweight Contracts/145/en

2020-08-11T00:38:23Z

FuzzyBot: Importing a new version from external source

As explained above, contract deployment is a two-step process, first the contract code is deployed using a cloud data transaction then a contract reference transaction is submitted to provide an entry point to the correct version of the contract. While this deployment process can be accomplished manually using the Ardor APIs, it is much simpler to perform the deployment using the contract manager utility.

Translations:Lightweight Contracts/130/en

2020-08-11T00:38:22Z

FuzzyBot: Importing a new version from external source

Always start your contract code with input validity checks. For example, if your contract is triggered by a sendMoney transaction, make sure the payment recipient is the contract account and that the payment uses the expected chain, that the payment amount is correct, etc.

Translations:Lightweight Contracts/128/en

2020-08-11T00:38:22Z

FuzzyBot: Importing a new version from external source

To simplify contract development always attempt to concentrate all your source code into a single source file which defines the contract class itself and possibly additional inner classes. When deploying the contract to the blockchain the contract manager loads the main contract class and checks if it has inner classes. If there are no inner classes, the contract class file is deployed to the blockchain, otherwise, the contract manager packs the contract and all its inner classes into a Jar file and deploys the Jar file to the blockchain.

Translations:Lightweight Contracts/125/en

2020-08-11T00:38:22Z

FuzzyBot: Importing a new version from external source

To learn more about the internal design of the lightweight contracts framework see [https://medium.com/@lyaffe/lightweight-contracts-design-f37fa5211bae this article]

Translations:Lightweight Contracts/121/en

2020-08-11T00:38:22Z

FuzzyBot: Importing a new version from external source

Unlike most smart contract frameworks, lightweight contracts support access to external resources. Your contract can communicate as client of any external service which provides a Java client API library, or Http, XML, Json, Soap, ldap, or a similar interface.

Translations:Lightweight Contracts/106/en

2020-08-11T00:38:22Z

FuzzyBot: Importing a new version from external source

In most cases, contracts should not save any internal state between contract invocations. To make changes to the blockchain state, contracts should submit transactions. To submit a transaction, invoke the API caller for the specific transaction type, then use the <code>context.createTransaction()</code> method to submit the transaction to the blockchain.
Internally the createTransaction method implements local signing, fee calculation, and other complex processing that you as contract developer don't have to deal with.

Translations:Lightweight Contracts/83/en

2020-08-11T00:38:22Z

FuzzyBot: Importing a new version from external source

For example, this is the HelloWorld sample contract.

Translations:Lightweight Contracts/82/en

2020-08-11T00:38:22Z

FuzzyBot: Importing a new version from external source

Under the Ardor module, there are two Java source roots, the first contains the sample contracts, the second contains the unit tests for the sample contracts.

Translations:Lightweight Contracts/67/en

2020-08-11T00:38:21Z

FuzzyBot: Importing a new version from external source

If you installed Ardor into a read-only folder you will need to copy it to a folder for which you have write permissions.

Translations:Lightweight Contracts/48/en

2020-08-11T00:38:21Z

FuzzyBot: Importing a new version from external source

The contract manager connects to an Ardor node to use the Ardor APIs and submit transactions. By default, it connects to a node running on localhost. Use the <code>contract.manager.serverAddress=[Server Address]</code> property to connect the contract manager to a remote node. The contract manager will never submit its passphrase to a remote node.

Translations:Lightweight Contracts/44/en

2020-08-11T00:38:21Z

FuzzyBot: Importing a new version from external source

The contract manager is a command-line utility that manages the contract lifecycle. Its primary usage is to deploy contracts to the blockchain, use it also to add or change a reference to an existing contract, to update contract setup parameters, to remove old contract references, and to verify that a specific contract was compiled from a specific Java source file.

Translations:Lightweight Contracts/39/en

2020-08-11T00:38:21Z

FuzzyBot: Importing a new version from external source

In response, you'll receive an array of contracts supported by the specific contract runner and their properties, and the contractAccount parameter which specifies the owner account of the contract runner, which is based on the passphrase or account id you specified in the contract runner configuration.

Translations:Lightweight Contracts/30/en

2020-08-11T00:38:21Z

FuzzyBot: Importing a new version from external source

Note that in most cases there is no need to specify these parameters. Always prefer using contract setup parameters that are stored on the blockchain itself except when a contract parameter has to remain secret (for example, a passphrase or some secret credentials to a 3rd party service).

Translations:Lightweight Contracts/28/en

2020-08-11T00:38:21Z

FuzzyBot: Importing a new version from external source

'''"seed"''' - supply random seed to the contract runner formatted as hex string (default: the public key of the contract account which is useless from randomness perspective). Convert any random value to hex string using the hexConvert API and specify the resulting hex string value as a seed. A seed of less than 16 bytes can be easily brute-forced so make sure your seed is longer. Keep your seed secret, it can be used in the future to validate your contract execution.

Translations:Lightweight Contracts/27/en

2020-08-11T00:38:21Z

FuzzyBot: Importing a new version from external source

'''"catchUpInterval"''' - a timeout value specified in seconds (default: 3600 i.e. one hour). During blockchain download, the contract runner will only submit transactions when downloading a block with a timestamp later than the current time minus the defined ''catchUpInterval''. The purpose of this setting is to prevent a contract runner from flooding the unconfirmed transaction pool with duplicate transactions during blockchain download.