Phased Transactions

Introduction

Nxt 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.

In this guide, all examples begin with phased Send NXT transactions created in the Nxt Client; the procedures are similar for other types of phasing-safe transactions supported by the Nxt Client.

This guide describes Phasing as of Nxt software release 1.5.13.

Create a Phased Transaction

To create a phased Send NXT transaction, first click on Send NXT at the center top of the Nxt Client. A pop-up entry form appears:

• At this point the recipient account ID and the amount of NXT to send can be entered into the Recipient and Amount fields of the form, respectively.
• If the Send NXT button in the lower right of the form is clicked, a transaction is created and immediately submitted to the peer network for inclusion in the blockchain, for a fee of 1 NXT.
• To instead make the transaction phased, click on the advanced link in the lower left area of the form to display the phasing related fields:

• To return to the basic Send NXT 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 Fee field contains the default minimum transaction fee of 1 NXT. The box to the right with the gavel graphic automatically displays the fee surcharge for phasing, depending on the phasing configuration.
• The Deadline (Hours) field displays the default 24 hour deadline for inclusion of the transaction into a block.
• The next row contains eight graphics for selecting the phasing voting model; hovering the cursor over the graphics causes descriptive tooltips to appear. The leftmost selection, the default, is for no phasing. The seven voting models are explained below.

Voting Models

Clicking on one of the phasing graphics selects the voting model, causes the fee surcharge to be updated and causes one or more new fields or controls to appear, as described in the sections below.

All voting models have in common a field/control for 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 voting models are named according to the method of approval.

For four of the voting models (the Vote By ... models), the results of a vote determine whether execution will occur at the finish height. These four 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 NXT, an asset or a currency.

None

If the second graphic is clicked, the following appears:

• The phased transaction will execute unconditionally at the Finish Height.
• The fee surcharge is +1 NXT.

Vote By Account

If the third 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 is +1 NXT.
• 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 NXT, an asset or a currency using the Min Balance Type drop-down control.
• Update the Finish Height field to change the default value.

Vote By Account Balance

If the fourth graphic is clicked, the following appears:

• Enter into the Amount NXT field the minimum total amount of NXT needed to approve the transaction, with each voting account contributing to the total its NXT balance (including any outgoing pending phased transfers) just prior to the phasing poll's completion.
• The fee surcharge is +20 NXT.
• 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 NXT using the Min Balance Type drop-down control.
• Update the Finish Height field to change the default value.

Vote By Asset Balance

If the fifth 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 +20 NXT.
• 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.
• Update the Finish Height field to change the default value.

Vote By Currency Balance

If the sixth 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 +20 NXT.
• 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.
• Update the Finish Height field to change the default value.

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 Nxt 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 Nxt API, but currently only one can be linked via this entry form.
• The fee surcharge is +1 NXT.
• Update the Finish Height field to change the default value.

By Secret

If the eigth graphic is clicked, the following appears:

• Select a Hash Algorithm from the pull-down control.
• Enter into the Approved By Hashed Secret field the hash of a secret phrase that must be revealed by the finish height to approve execution of the phased transaction. The hash can be computed from the secret phrase using the Calculate Hash item of the Settings Menu.
• The fee surcharge is +1 NXT.
• 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.

Finish Height

Selection of any voting model causes the Finish Height field and its associated controls to appear:

• The leftmost box 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).

Whitelist

Selection of one of the four 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

Selection of one of the four 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 NXT 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 NXT and one or more new fields to appear as described in the following subsections.

Minimum Balance Of NXT

• Enter into the Min Balance field the minimum balance of NXT 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.

Approve A Phased Transaction

Approval Requests are the best mechanism for approval of phased transactions, but they only apply to the four 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 four Vote By ... voting models. While voting is open (until the finish height of the phasing poll is reached), approval requests appear in all Nxt 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 Nxt 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 Nxt 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 Nxt 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 Nxt 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
	None	None
	Vote By Account	Current / Required approvals (votes)
	Vote By Account Balance	Total NXT 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%
	By Linked Transactions	Linked Transactions progress scale, 0% to 100%
	By Secret	Secret revealed 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 NXT, 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.