Almonte at 15:50, 18 May 2021

2021-05-18T15:50:56Z

New page

<languages />
<translate>
{{#seo:
|title=Phasing
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki, Phasing
|description=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
}}
[[Category:Features]]
__TOC__
==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|Create Transaction]] list. See also the API for [[Phasing#Create_Phased_Transaction|creating a phase transaction]]
In this guide, all examples begin with phased ''Send IGNIS'' transactions created in the [[Ardor_client_interface|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:
[[File:Approval_models.png|none|border|600px]]
*When clicking on add approval model, a pop-up entry form appears:
[[File:Add_approval_model.png|none|border|630px]]

===Voting Models=== 


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


All voting models have a [[Phasing (f)#Finish_Height|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 [[Phasing (f)#Create_a_Phased_Transaction|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 [[Phasing (f)#Whitelist|Whitelist]] field for restricting voting to selected accounts and for generating [[Phasing (f)#Whitelisted_Approval_Requests|Whitelisted Approval Requests]], and the [[Phasing (f)#Minimum_Balance_Models|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:
[[File:Phasing_deferred.png|none|border|630px]]
*Transaction execution is deferred, however transaction does not need further approval to become valid at the [[Phasing (f)#Finish_Height|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:
[[File:Phasing_vote_by_account.png|none|border|630px]]
*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 [[Phasing (f)#Whitelist|Whitelist]] can be used to restrict voting and to generate [[Phasing (f)#Whitelisted_Approval_Requests|Whitelisted Approval Requests]]. Otherwise, the only mechanism for voting is [[Phasing (f)#Manual_Approval|Manual Approval]].
*Voting can be restricted to accounts with a minimum balance of ARDR, an asset or a currency using the [[Phasing (f)#Minimum_Balance_Models|Min Balance Type]] drop-down control.

====Vote By Account Balance==== 
If the third graphic is clicked, the following appears:
[[File:Phasing_vote_by_account_balance.png|none|border|630px]]
*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 [[Phasing (f)#Whitelist|Whitelist]] can be used to restrict voting and to generate [[Phasing (f)#Whitelisted_Approval_Requests|Whitelisted Approval Requests]]. Otherwise, the only mechanism for voting is [[Phasing (f)#Manual_Approval|Manual Approval]].
*Voting can be restricted to accounts with a minimum balance of IGNIS using the [[Phasing (f)#Minimum_Balance_Models|Min Balance Type]] drop-down control.

====Vote By Asset Balance==== 
If the fourth graphic is clicked, the following appears:
[[File:Phasing_vote_by_asset_balance.png|none|border|630px]]
*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 [[Phasing (f)#Whitelist|Whitelist]] can be used to restrict voting and to generate [[Phasing (f)#Whitelisted_Approval_Requests|Whitelisted Approval Requests]]. Otherwise, an [[Phasing (f)#Asset_Approval_Requests|Asset Approval Request]] is automatically generated.
*Voting can be restricted to accounts with a minimum balance of the asset using the [[Phasing (f)#Minimum_Balance_Models|Min Balance Type]] drop-down control.

====Vote By Currency Balance==== 
If the fifth graphic is clicked, the following appears:
[[File:Phasing_vote_by_currency_balance.png|none|border|630px]]
*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 [[Phasing (f)#Whitelist|Whitelist]] can be used to restrict voting and to generate [[Phasing (f)#Whitelisted_Approval_Requests|Whitelisted Approval Requests]]. Otherwise, an [[Phasing (f)#Currency_Approval_Requests|Currency Approval Request]] is automatically generated.
*Voting can be restricted to accounts with a minimum balance of the currency using the [[Phasing (f)#Minimum_Balance_Models|Min Balance Type]] drop-down control.

====Vote By Property==== 
If the sixth graphic is clicked, the following appears:
[[File:Phasing_vote_by_property.png|none|border|630px]]
*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:
[[File:Phasing_by_linked_transactions_2.png|none|border|630px]]
*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 [[Ardor_client_interface#My_Transactions|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 [[Transactions#Get_Transaction|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 [[Ardor_client_interface#Settings_Menu|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 [[Phasing#Create_Phasing_Poll|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:
[[File:Phasing_by_secret.png|none|border]]
*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 [[Phasing (f)#Finish_Height|Finish Height]] field to change the default value.
*To approve the phased transaction once it is confirmed and before the finish height, use [[Phasing (f)#Manual_Approval|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.
[[File:ApprovalModels-Hash.png|border]]
[[File:Reproduce Secret modal.png|border]]

====Composite Phasing==== 
If the ninth graphic is clicked, the following appears:
[[File:Phasing_composite.png|none|border|630px]]
*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|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 ...'' [[Phasing (f)#Voting_Models|voting models]] causes the ''Accounts (Whitelist)'' field and its associated controls to appear:
[[File:Phasing_whitelist.png|none|border|630px]]
*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 [[Phasing (f)#Whitelisted_Approval_Requests|Whitelisted Approval Request]], which is a mechanism for voting.

===Minimum Balance Models=== 
Creation an approval model of one of the ''Vote By ...'' [[Phasing (f)#Voting_Models|voting models]] causes the ''Min Balance Type'' drop-down control to appear:
[[File:Phasing_min_balance_box.png|none|border|630px]]
*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:
[[File:Phasing_min_balance.png|none|thumb|border|630px]]
*The list shown is for the [[Phasing (f)#Vote_By_Account|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 [[Phasing (f)#Vote_By_Account_Balance|Vote By Account Balance]], [[Phasing (f)#Vote_By_Asset_Balance|Vote By Asset Balance]] or [[Phasing (f)#Vote_By_Currency_Balance|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==== 
[[File:Phasing_min_balance_ardor.png|none|border|630px]]
*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==== 
[[File:Phasing_min_balance_asset.png|none|border|630px]]
*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 [[Phasing (f)#Vote_By_Account|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 [[Phasing (f)#Vote_By_Asset_Balance|Vote By Asset Balance]] voting model, because the asset ID is already specified.

====Minimum Balance Of Currency Units==== 
[[File:Phasing_min_balance_currency.png|none|border|630px]]
*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 [[Phasing (f)#Vote_By_Account|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 [[Phasing (f)#Vote_By_Currency_Balance|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.
[[File:Phasing_send_ardor_basic.png|none|border|630px]]
To create a phased transaction, click on the ''Advanced'' link in the lower left area of the form to display the phasing related fields:
[[File:Phasing_send_ardor_advanced.png|none|border|630px]]
*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=== 
[[File:Phasing_finish_height.png|none|border|630px]]
*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== 
[[Phasing (f)#Approval_Requests|Approval Requests]] are the best mechanism for approval of phased transactions, but they only apply to the ''Vote By ...'' [[Phasing (f)#Voting_Models|voting models]], and in the cases of [[Phasing (f)#Vote_By_Account|Vote By Account]] and [[Phasing (f)#Vote_By_Account_Balance|Vote By Account Balance]], only when a [[Phasing (f)#Whitelist|Whitelist]] is used. Otherwise, and including the [[Phasing (f)#By_Secret|By Secret]] voting model, another mechanism must be used: [[Phasing (f)#Manual_Approval|Manual Approval]]. The [[Phasing (f)#By_Linked_Transactions|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 ...'' [[Phasing (f)#Voting_Models|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 [[Phasing (f)#Whitelisted_Approval_Requests|Whitelisted Approval Requests]] screen, regardless of the voting model.


Absent a whitelist, [[Phasing (f)#Vote_By_Account|Vote By Account]] and [[Phasing (f)#Vote_By_Account_Balance|Vote By Account Balance]] voting model approval requests appear nowhere in the Ardor Client while [[Phasing (f)#Vote_By_Asset_Balance|Vote By Asset Balance]] and [[Phasing (f)#Vote_By_Currency_Balance|Vote By Currency Balance]] voting model approval requests appear on the [[Phasing (f)#Asset_Approval_Requests|Asset Approval Requests]] and [[Phasing (f)#Currency_Approval_Requests|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:
[[File:Phasing_account_approval.png|none|thumb|border|630px]]
*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 [[Phasing (f)#Vote_By_Account|Vote By Account]] and [[Phasing (f)#Vote_By_Account_Balance|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 (f)#View_Phasing_Poll_Status|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:
[[File:Phasing_asset_approval.png|none|thumb|border|630px]]
*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 (f)#View_Phasing_Poll_Status|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:
[[File:Phasing_currency_approval.png|none|thumb|border|630px]]
*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 (f)#View_Phasing_Poll_Status|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 [[Ardor_client_interface#My_Transactions|My Transactions]] screen but that uses neither the [[Phasing (f)#None|None]] nor the [[Phasing (f)#By_Linked_Transactions|By Linked Transactions]] voting model, approval can be accomplished by the following procedure:
#click on the timestamp of the transaction to open the ''Transaction Info'' pop-up window
#click on the ''Actions'' tab
#click on the ''Approve Transaction'' button to open the ''Approve Transaction'' pop-up window
#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 [[Ardor_client_interface#Blocks|Blocks]] screen by clicking on the block height. Otherwise, the [[Phasing#Approve_Transaction|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 [[Transactions#Get_Transaction|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 [[Phasing (f)#Approval_Requests|Approval Requests]] screen while the phasing poll is open and on the [[Ardor_client_interface#My_Transactions|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=== 
{| class="wikitable"
|-
! Graphic
! Voting Model
! Status Indicator
|-
| [[File:Phasing_status_none.png|border]]
| [[Phasing (f)#Deferred|Deferred]]
| None
|-
| [[File:Phasing_status_account_number.png|border]]
| [[Phasing (f)#Vote_By_Account|Vote By Account]]
| Current / Required approvals (votes)
|-
| [[File:Phasing_status_account_balance.png|border]]
| [[Phasing (f)#Vote_By_Account_Balance|Vote By Account Balance]]
| Total IGNIS or child chain tokens balance progress scale, 0% to 100%
|-
| [[File:Phasing_status_asset.png|border]]
| [[Phasing (f)#Vote_By_Asset_Balance|Vote By Asset Balance]]
| Total asset balance progress scale, 0% to 100%
|-
| [[File:Phasing_status_currency.png|border]]
| [[Phasing (f)#Vote_By_Currency_Balance|Vote By Currency Balance]]
| Total currency balance progress scale, 0% to 100%
|-
| [[File:Phasing_status_property.png|border]]
| [[Phasing (f)#Vote_By_Property|Vote By Property]]
| Current vote by property progress scale, 0% to 100%
|-
| [[File:Phasing_status_transaction.png|border]]
| [[Phasing (f)#By_Linked_Transactions|By Linked Transactions]]
| Linked Transactions progress scale, 0% to 100%
|-
| [[File:Phasing_status_secret.png|border]]
| [[Phasing (f)#By_Secret|By Secret]]
| Secret revealed progress scale, binary: 0% or 100%
|-
| [[File:Phasing_status_composite.png|border]]
| [[Phasing (f)#Composite_Phasing|Composite Phasing]]
| Composite progress scale, binary: 0% or 100%
|}

===Graphic Status Indicator Color Codes=== 
{| class="wikitable"
|-
! Graphic
! Color
! Approval Status
|-
| [[File:Phasing_status_currency.png|border]]
| Gold
| Not yet approved; phasing poll still open
|-
| [[File:Phasing_status_currency_disapproved.png|border]]
| Red
| Disapproved; phasing poll finished, transaction ignored
|-
| [[File:Phasing_status_currency_approved.png|border]]
| Green
| Approved; phasing poll finished, transaction executed
|}

===Graphic Status Indicator Tooltips=== 
[[File:Phasing_status_tooltip.png|left|border]]


{|
|'''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.
|}
</translate>

Phasing Transactions - Revision history

Almonte at 15:50, 18 May 2021