Phasing Transactions

Introduction

Ardor Phasing is a feature that allows certain phasing-safe transactions to be created with conditional deferred execution based on the result of a vote, on a list of linked transactions or on the revelation of a secret; or simply with unconditional deferred execution. Phasing-safe transactions are indicated with italics in the API Create Transaction list. See also the API for creating a phase transaction In this guide, all examples begin with phased Send IGNIS transactions created in the Ardor Client; the procedures are similar for other types of phasing-safe transactions supported by the Ardor Client.

Create an Approval Model

Approval models are the conditions that can be linked to a phased transaction. In order to an approval to be created, click on Approval Models at the left of the Ardor client, under the Dashboard:

• When clicking on add approval model, a pop-up entry form appears:

Voting Models

The voting models are named according to the method of approval.

All voting models have a Finish Height which determines when deferred execution will occur if approved, that is, if all requirements for execution will have been met in the block just prior to the finish height. The finish height is specified when creating the phasing transaction, not when defining the approval model.

For the voting models (the Vote By ... models), the results of a vote determine whether execution will occur at the finish height. These models have in common: the Whitelist field for restricting voting to selected accounts and for generating Whitelisted Approval Requests, and the Min Balance Type control for restricting voting to accounts with a minimum balance of Ignis or other child chain tokens (eg: GPS, BITS), an asset or a currency.

Deferred

If the first graphic is clicked, the following appears:

• Transaction execution is deferred, however transaction does not need further approval to become valid at the Finish Height.
• The fee surcharge for the phasing appending is 0.01 ARDR.

Vote By Account

If the second graphic is clicked, the following appears:

• Enter into the Number Accounts field the number of accounts that must vote for (approve) the transaction. Each account has one vote.
• The fee surcharge for phasing appendix is 0.01 ARDR when balance independent and 0.2 ARDR when balance dependent.
• A Whitelist can be used to restrict voting and to generate Whitelisted Approval Requests. Otherwise, the only mechanism for voting is Manual Approval.
• Voting can be restricted to accounts with a minimum balance of ARDR, an asset or a currency using the Min Balance Type drop-down control.

Vote By Account Balance

If the third graphic is clicked, the following appears:

• Enter into the Amount IGNIS field the minimum total amount of IGNIS needed to approve the transaction, with each voting account contributing to the total its IGNIS balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
• The fee surcharge is +0.02 ARDR.
• A Whitelist can be used to restrict voting and to generate Whitelisted Approval Requests. Otherwise, the only mechanism for voting is Manual Approval.
• Voting can be restricted to accounts with a minimum balance of IGNIS using the Min Balance Type drop-down control.

Vote By Asset Balance

If the fourth graphic is clicked, the following appears:

• Enter into the Asset Quantity field the minimum total quantity of the asset needed to approve the transaction, with each voting account contributing to the total its asset balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
• Enter into the Asset field the asset ID. The name of the asset is instantly displayed in the shaded box to the right to confirm the ID.
• The fee surcharge is +0.2 ARDR.
• A Whitelist can be used to restrict voting and to generate Whitelisted Approval Requests. Otherwise, an Asset Approval Request is automatically generated.
• Voting can be restricted to accounts with a minimum balance of the asset using the Min Balance Type drop-down control.

Vote By Currency Balance

If the fifth graphic is clicked, the following appears:

• Enter into the Currency Units field the minimum total units of the currency needed to approve the transaction, with each voting account contributing to the total its currency balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
• Enter into the Currency field the three- to five-letter currency code. The ID of the currency is instantly displayed in the shaded box to the right to confirm the code.
• The fee surcharge is +0.2 ARDR.
• A Whitelist can be used to restrict voting and to generate Whitelisted Approval Requests. Otherwise, an Currency Approval Request is automatically generated.
• Voting can be restricted to accounts with a minimum balance of the currency using the Min Balance Type drop-down control.

Vote By Property

If the sixth graphic is clicked, the following appears:

• Transaction is executed only if the sender or recipient have certain account properties. If both the sender and recipient properties are set then the transaction must match both. Please note that transactions that have no recipient (i.e. data cloud upload) are not checked for the recipient property.
• Enter into the Sender Property Setter the account id of the setter of the property that the sender needs for the transaction to be executed.
• Enter into the Recipient Property Setter the account id of the recipient of the property that the recipient needs for the transaction to be executed.
• Enter into the Sender Property Name and Sender Property Value the pair name and value.
• The fee surcharge is +0.01 ARDR.

By Linked Transactions

If the seventh graphic is clicked, the following appears:

• Enter the full hash of a transaction that must be in the blockchain at the finish height for the phased transaction to be executed.
• A transaction already in the blockchain before the acceptance of the phased transaction can be linked, as long as it is not more than 60 days old, or itself a phased transaction. If the transaction is associated with your account, its full hash can be obtained by clicking on its timestamp in the My Transactions screen to open the Transaction Info pop-up window, then clicking on the Transactions Detail tab. Otherwise, the full hash can be obtained using the Ardor API if the transaction ID is known.
• A transaction not yet in the blockchain can be linked in advance if the transaction is created but not broadcast. The full hash is then available for linking to the phased transaction. The signed transaction bytes can be broadcast later (via the Transaction Operations item of the Settings Menu), before the finish height of the phased transaction, in order to approve it.
• It is possible to link up to ten transactions via the Ardor API, but currently only one can be linked via this entry form.
• The fee surcharge is +0.01 ARDR.

By Secret

If the eigth graphic is clicked, the following appears:

• Enter your secret phrase in order to generate a reproducible secret.
• Select a Hash Algorithm from the pull-down control.
• The Generated Secret field will show the secret that must be revealed by the finish height to approve execution of the phased transaction. The hash of the secret is shown in the Approved by Hashed Secret field.
• The fee surcharge is +0.01 ARDR.
• Update the Finish Height field to change the default value.
• To approve the phased transaction once it is confirmed and before the finish height, use Manual Approval.
• If you need to reproduce the secret again you can do so easily by selecting the Reproduce Secret button from the approval model you've created.

Composite Phasing

If the ninth graphic is clicked, the following appears:

• Write a boolean expression in Boolean Expression for conditional transactions to be defined in terms of a Boolean Expression of other approvals mode.
• See more information of composite phasing
• The fee is determined by phasing complexity based on 0.02 + 0.02 ARDR per 32b + per poll fees

Whitelist

Creation an approval model of one of the Vote By ... voting models causes the Accounts (Whitelist) field and its associated controls to appear:

• Enter into the Accounts (Whitelist) field the account ID of an account that is eligible to vote.
• Once the whitelist is created with the inclusion of a single account, only that account and up to nine other accounts optionally added to the whitelist are eligible to vote in the phasing poll.
• To add another account to the whitelist, click on the + Add Account button and enter the account ID into the new field that appears.
• To remove an account from the whitelist, click on the - (minus) control on the right.
• Whitelisted accounts will receive a Whitelisted Approval Request, which is a mechanism for voting.

Minimum Balance Models

Creation an approval model of one of the Vote By ... voting models causes the Min Balance Type drop-down control to appear:

• The default selection is No min balance necessary, meaning that possessing a minimum balance is not an eligibility requirement for voting. There is no additional fee surcharge.

Clicking on the drop-down control causes a list of one or more minimum balance models (types) to appear, depending on the voting model:

• The list shown is for the Vote By Account model and offers a choice of three minimum balance models: Min balance of ARDR required, Min balance of asset quantity required and Min balance of currency units required.
• If the voting model is Vote By Account Balance, Vote By Asset Balance or Vote By Currency Balance, the minimum balance model must match the voting model and so only one choice is offered for each.
• Selecting one of the minimum balance models causes the fee surcharge to be +20 ARDR and one or more new fields to appear as described in the following subsections.

Minimum Balance Of Ignis

• Enter into the Min Balance field the minimum balance of Ignis required for an account to be eligible to vote in the phasing poll for approval of the transaction.
• The account must possess this minimum balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.

Minimum Balance Of Asset Quantity

• Enter into the Min Balance field the minimum balance of asset quantity required for an account to be eligible to vote in the phasing poll for approval of the transaction.
• The account must possess this minimum balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
• If the voting model is Vote By Account, enter into the Asset field the asset ID. The name of the asset is instantly displayed in the shaded box to the right to confirm the ID. This field is not displayed for the Vote By Asset Balance voting model, because the asset ID is already specified.

Minimum Balance Of Currency Units

• Enter into the Min Balance field the minimum balance of currency units required for an account to be eligible to vote in the phasing poll for approval of the transaction.
• The account must possess this minimum balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
• If the voting model is Vote By Account, enter into the Currency field the three- to five-letter currency code. The ID of the currency is instantly displayed in the shaded box to the right to confirm the code. This field is not displayed for the Vote By Currency Balance voting model, because the currency code is already specified.

Create a Phased Transaction

The wallet allows you to send any transaction as phased from the same pop-up form used to submit the transaction data.

To create a phased transaction, click on the Advanced link in the lower left area of the form to display the phasing related fields:

• To return to the basic form, click on the Basic link in the lower left area of the form.
• The Referenced Transaction Hash field and the Do Not Broadcast and Note to Self? controls do not relate to Phasing.
• The Phasing Approval Model contains all the approvals models created to be used as phase transactions.

Finish Height

• Next to the approval model selector is the entry field for Finish Height and is initialized to 7000 blocks (approximately a week) into the future. Enter the exact block height at which the phasing poll is to finish.
• As a convenience, an estimated finish date is displayed to the right of the Finish Height label. This date adjusts automatically whenever the Finish Height field changes.
• As a convenience, the second shaded box just to the right of the Finish Height field is a control which displays the current block height at the time the pop-up entry form was opened. Clicking on it causes the Finish Height field to change to this value.
• As a convenience, the third and fourth boxes contain controls labeled - (minus) and + (plus) for decreasing or increasing, respectively, the Finish Height by 500 blocks (approximately half of a day).

Approve A Phased Transaction

Approval Requests are the best mechanism for approval of phased transactions, but they only apply to the Vote By ... voting models, and in the cases of Vote By Account and Vote By Account Balance, only when a Whitelist is used. Otherwise, and including the By Secret voting model, another mechanism must be used: Manual Approval. The By Linked Transactions voting model does not require manual approval, only the presence of the specified linked transaction(s) in the blockchain.

Approval Requests

Approval requests are invitations to vote in phasing polls, which apply to the Vote By ... voting models. While voting is open (until the finish height of the phasing poll is reached), approval requests appear in all Ardor Clients logged into accounts that are invited to vote in the poll, either by inclusion on a whitelist or by virtue of owning an asset or currency, depending on the voting configuration.

If a whitelist is used, then approval requests appear only on the Whitelisted Approval Requests screen, regardless of the voting model.

Absent a whitelist, Vote By Account and Vote By Account Balance voting model approval requests appear nowhere in the Ardor Client while Vote By Asset Balance and Vote By Currency Balance voting model approval requests appear on the Asset Approval Requests and Currency Approval Requests screens, respectively.

Whitelisted Approval Requests

This screen is accessed from the Ardor Client menu in the left pane by first clicking on Dashboard to expand the submenu, then clicking on the Approval Requests submenu item:

• Note that the number of pending approval requests is displayed in a shaded circle to the right of the Approval Requests submenu item; this is an alert that approvals are requested.
• (Account) in the screen title refers to the Vote By Account and Vote By Account Balance voting models for which whitelisting is required to generate approval requests, but this screen also includes the other two voting models when a whitelist is used and so would more accurately be represented as (Whitelisted).
• Details of phased transactions with open phasing polls are shown in each row of the list with an Approve button in the Actions column; the graphic in the gavel column indicates the phasing poll status.
• The Approve button is highlighted and active if the logged-in account has not yet voted; after voting it becomes shaded and inactive.
• Clicking on the Approve button opens an Approve Transaction pop-up entry form; then clicking on Approve creates an approval transaction.

Asset Approval Requests

This screen is accessed from the Ardor Client menu in the left pane by first clicking on Asset Exchange to expand the submenu, then clicking on the Approval Requests submenu item; finally, select an asset from the drop-down list control under the screen title:

• Details of phased transactions with open phasing polls are shown in each row of the list with an Approve button in the Actions column; the graphic in the gavel column indicates the phasing poll status.
• The Approve button is highlighted and active if the logged-in account has not yet voted; after voting it becomes shaded and inactive.
• Clicking on the Approve button opens an Approve Transaction pop-up entry form; then clicking on Approve creates an approval transaction.

Currency Approval Requests

This screen is accessed from the Ardor Client menu in the left pane by first clicking on Monetary System to expand the submenu, then clicking on the Approval Requests submenu item; finally, select a currency from the drop-down list control under the screen title:

• Details of phased transactions with open phasing polls are shown in each row of the list with an Approve button in the Actions column; the graphic in the gavel column indicates the phasing poll status.
• The Approve button is highlighted and active if the logged-in account has not yet voted; after voting it becomes shaded and inactive.
• Clicking on the Approve button opens an Approve Transaction pop-up entry form; then clicking on Approve creates an approval transaction.

Manual Approval

For any phased transaction that appears on the My Transactions screen but that uses neither the None nor the By Linked Transactions voting model, approval can be accomplished by the following procedure:

1. click on the timestamp of the transaction to open the Transaction Info pop-up window
2. click on the Actions tab
3. click on the Approve Transaction button to open the Approve Transaction pop-up window
4. click on the Approve button to approve the transaction, after entering the secret phrase in the case of the By Secret voting model

Only (confirmed) transactions that are directly connected with the logged-in account appear on this screen, including transactions sent or received, and those with phased polls with an invitation to vote (approval request).

When there is no approval request and the phased transaction does not appear on the My Transactions screen, it can still be found if the block height of the block containing the transaction is known, via the Blocks screen by clicking on the block height. Otherwise, the Approve Transaction API call can be used if the full hash of the phased transaction is known, and the full hash can be obtained using the Get Transaction API call if the transaction ID is known.

View Phasing Poll Status

The status of a phasing poll is indicated by a golden graphic which appears on an Approval Requests screen while the phasing poll is open and on the My Transactions screen, where the graphic changes color to green (approved) or red (disapproved) upon phasing poll completion at the finish height. A tooltip appears when the cursor hovers over the graphic, displaying status details.

The status can change until the phasing poll's completion, when it freezes. At the finish height, the phased transaction is executed only if all requirements for approval are met in the block just prior to the finish block.

Graphic Status Indicators

Graphic	Voting Model	Status Indicator
	Deferred	None
	Vote By Account	Current / Required approvals (votes)
	Vote By Account Balance	Total IGNIS or child chain tokens balance progress scale, 0% to 100%
	Vote By Asset Balance	Total asset balance progress scale, 0% to 100%
	Vote By Currency Balance	Total currency balance progress scale, 0% to 100%
	Vote By Property	Current vote by property progress scale, 0% to 100%
	By Linked Transactions	Linked Transactions progress scale, 0% to 100%
	By Secret	Secret revealed progress scale, binary: 0% or 100%
	Composite Phasing	Composite progress scale, binary: 0% or 100%

Graphic Status Indicator Color Codes

Graphic	Color	Approval Status
	Gold	Not yet approved; phasing poll still open
	Red	Disapproved; phasing poll finished, transaction ignored
	Green	Approved; phasing poll finished, transaction executed

Graphic Status Indicator Tooltips

Accounts/Asset/Currency: The number of whitelisted accounts or the name of the asset or currency holding.

Votes: The number of accounts or the amount of ARDR, child chain tokens, asset QNT or currency Units in Current approvals / Required approvals format.

Percentage: Current approvals as a percentage of Required approvals.

Finish Height: The block height at which the phasing poll finishes or finished.

Approved: Yes only if all requirements were met at phasing poll completion, No if not or if the phasing poll is still open.